# Решение проблем

> Решения частых проблем DuckLocal: команда ducklocal не найдена, файлы не присоединяются, базы данных не открываются, зависшие запросы, S3 и дашборды.

Source: https://ducklocal.app/docs/ru/troubleshooting

Найдите симптом, прочитайте причину и примените решение. Если вашей проблемы нет
в списке, [откройте issue](https://github.com/JetSquirrel/DuckLocal/issues),
описав, что вы делали и что произошло.

## Установка и запуск

| Симптом | Причина и решение |
| --- | --- |
| Приложение не открывается на Intel Mac | Выпуск для macOS собран только для Apple silicon. [Соберите из исходного кода](development.md#build-and-run) на Intel |
| Сочетания клавиш из этой документации ничего не делают в Windows или Linux | Читайте **Ctrl** вместо **⌘**: там ⌘↵ — это Ctrl+Enter |
| `ducklocal: command not found` | Образ диска устанавливает приложение, а не команду. [Слинкуйте бинарный файл в PATH](getting-started.md#add-command) |
| Терминал занят, пока открыто окно | Запуск GUI из терминала выполняется на переднем плане. Запускайте приложение из «Программ» или оставьте этот терминал ему |
| История, настройки или запомненные файлы перестают сохраняться | Работает второй экземпляр DuckLocal и держит файл данных приложения. Закройте другой и запустите заново |
| **В прошлый раз DuckLocal завершился неожиданно** | Он аварийно завершился и сохранил отчёт в папке журналов. Нажмите **Показать отчёт** и приложите его к [issue](https://github.com/JetSquirrel/DuckLocal/issues) — см. [где что хранится](settings-and-data.md#where-things-are-stored) |
| **Не удалось проверить обновления** | Наведите курсор, чтобы увидеть причину: нет сети, прокси или загрузка не совпала с контрольной суммой. Нажмите, чтобы повторить, или скачайте выпуск с GitHub — см. [Проверка обновлений](settings-and-data.md#update-check) |

## Открытие данных

| Симптом | Причина и решение |
| --- | --- |
| `File not found` для указанного вами пути | Путь не существует или отсчитывается от другого каталога, чем вы думаете. Используйте абсолютный путь, чтобы быть уверенным |
| Папка сообщает, что файлов данных нет | Ничто внутри не совпало с `.csv`, `.tsv`, `.txt`, `.parquet`, `.json`, `.ndjson`, `.jsonl`, `.xlsx`, `.xls`, `.xlsb` или `.ods` |
| Папка дала меньше файлов, чем ожидалось | Скрытые элементы и символические ссылки пропускаются, а один запрос открытия присоединяет не более 256 файлов. Открывайте подпапки отдельно |
| Путь неожиданно открылся как база данных | Любой существующий файл, не являющийся файлом данных, рассматривается как база данных DuckDB. Если она не открывается, DuckLocal сообщает причину; при запуске он переходит к памяти. См. [Открытие базы данных](#opening-a-database) |
| **Not attached …: the database already has a table or view named …** | База данных уже содержит таблицу или представление с тем же именем, что у запомненного файла. DuckLocal никогда не заменяет её. Переименуйте или удалите одну из двух либо удалите файл из **Локальных файлов** и откройте снова, чтобы получить новое имя |
| **Cannot restore relative path …** | Файл был запомнен по относительному пути, который нельзя разрешить в новом сеансе. Удалите его из **Локальных файлов** и откройте снова |
| Представление показывает `sales_2` вместо `sales` | Другой файл или таблица уже имели это имя, поэтому новое получило суффикс |
| Представление файла устарело | Представления читают файл при каждом запросе. Если столбцы CSV изменили форму, используйте **Обновить схему** в боковой панели |

## Открытие базы данных {#opening-a-database}

| Симптом | Причина и решение |
| --- | --- |
| Сообщение говорит, что база данных создана более новой версией DuckDB | Файл использует формат хранения более новый, чем читает встроенная в DuckLocal DuckDB. Выполните строки `ATTACH … COPY FROM DATABASE` из сообщения в той DuckDB, которая создала файл, затем откройте копию. См. [Когда база данных не открывается](data-sources.md#when-a-database-will-not-open) |
| Сообщение говорит, что база данных из DuckDB v0.9 или старше | Выполните `EXPORT DATABASE 'dir'` в той DuckDB, которая её записала, затем `IMPORT DATABASE 'dir'` в DuckLocal |
| Сообщение говорит, что это база данных SQLite | Присоедините её через **Открыть → Присоединить базу данных…**, а не открывайте |
| Сообщение говорит, что файл не является базой данных DuckDB | Его расширение не относится к тем, что DuckLocal читает как данные, поэтому его попробовали как базу данных. Дайте ему [поддерживаемое расширение](data-sources.md#supported-file-formats) или прочитайте его в SQL, например `SELECT * FROM read_csv('export.dat')` |
| DuckDB сообщает, что не удалось установить блокировку файла | Другая программа — другая DuckDB, скрипт, второе приложение — держит базу данных открытой для записи, а DuckDB позволяет писать в файл только одному процессу. Закройте её там и снова откройте файл |
| DuckDB сообщает об отказе в доступе | Ваша учётная запись не может прочитать файл или не может записать его: основная база данных открывается для записи. Исправьте права на файл или присоедините его с отмеченным флажком **Только для чтения** |
| Открытие базы данных завершилось неудачей, и ничего не изменилось | Так и должно быть, пока DuckLocal работает: неудачное открытие оставляет рабочее пространство прежним. Прочитайте уведомление о причине |
| Подсказка в строке состояния говорит **читается DuckDB v1.x+**, а коллега не может открыть файл | Его DuckDB старше этой версии. Ему нужно обновиться, или вы копируете файл со старым `STORAGE_VERSION` — см. [Какой DuckDB может прочитать базу данных](data-sources.md#storage-version) |

## Присоединённые базы данных

| Симптом | Причина и решение |
| --- | --- |
| Присоединённая база данных пропала после перезапуска | Её файла не было по запомненному пути при запуске, поэтому она была пропущена. Регистрация сохранена; верните файл на место, и он вернётся при следующем подключении |
| **Эта база данных уже открыта как …** | Файл уже является основной базой данных или присоединён под этим именем. Запрашивайте её по этому имени |
| **Не удалось присоединить …: имя … занято в открытой базе данных.** | Что-то ещё в подключении уже использует запомненный псевдоним — например, база данных, присоединённая вами в SQL под тем же именем. Выполните `DETACH` для неё, затем снова откройте базу данных или перезапустите |
| Запись в присоединённую базу данных не удаётся | Она была присоединена только для чтения, что и является значением по умолчанию. Используйте **Отсоединить базу данных** в боковой панели, затем присоедините её снова со снятым флажком **Только для чтения** |
| Присоединение создало пустую базу данных | Со снятым **Только для чтения** несуществующий путь DuckDB создаётся. Отсоедините её, удалите пустой файл и проверьте путь |
| Имя таблицы без базы данных находит не ту таблицу | Имена без базы данных разрешаются в базе данных по умолчанию. Щёлкните базу данных правой кнопкой и выберите **Использовать как базу данных по умолчанию** или пишите `alias.table` |

## Finder и Quick Look

Всё это только для macOS.

| Симптом | Причина и решение |
| --- | --- |
| Двойной щелчок по файлу `.parquet` или `.duckdb` открывает другую программу | Эта программа уже выбрана по умолчанию. В Finder: **Свойства → Открыть с помощью**, выберите DuckLocal, затем **Изменить всё…** |
| Двойной щелчок по CSV или Excel не открывает DuckLocal | Так задумано: DuckLocal не перехватывает эти форматы. Используйте **Открыть с помощью → DuckLocal** или перетащите файл на значок в Dock |
| DuckLocal не предлагается в **Открыть с помощью**, или пробел не показывает предпросмотр DuckLocal | macOS ещё не зарегистрировала приложение. Переместите его в «Программы» и запустите один раз. Для предпросмотра затем выполните `qlmanage -r` в Терминале и проверьте, что **DuckLocal Preview** включён в разделе Quick Look в настройках расширений «Настроек системы» |
| Простой файл `.json` или файл Excel не показывает предпросмотр DuckLocal | Так задумано: они оставлены собственным предпросмотрам macOS. Файлы `.jsonl` и `.ndjson` показываются |
| Предпросмотр показывает только 50 строк | Так задумано: предпросмотр никогда не сканирует файл целиком. Откройте файл в DuckLocal, чтобы увидеть остальное |
| Предпросмотр файла `.duckdb` показывает ошибку | Предпросмотр читает файл собственной DuckDB DuckLocal, поэтому файл из более новой DuckDB не открывается и там. См. [Открытие базы данных](#opening-a-database) |

## Выполнение запросов

| Симптом | Причина и решение |
| --- | --- |
| **Выполнить** ничего не делает | Запрос уже выполняется. Нажмите **Остановить** рядом с «Выполнить» или **⌘.**, чтобы прервать его |
| Запрос завершился ошибкой `Interrupted` | Кто-то нажал **Остановить** (или ⌘.), пока он выполнялся. Запустите его снова |
| Часть SQL подчёркнута красной волнистой линией | Там произошёл сбой при последнем выполнении. Прочитайте сообщение *Запрос не выполнен*; отметка исчезнет при следующем выполнении |
| **⌘↵** показывает редактор вместо выполнения | На экране первого запуска ⌘↵ означает «дайте мне редактор». Нажмите ещё раз, чтобы выполнить |
| Результаты обрываются раньше с уведомлением об усечении | Достигнут предел в 100 000 строк или 2 000 000 ячеек. Сузьте запрос; постраничного вывода нет |
| Отметки времени выглядят смещёнными | Таблица отображает отметки времени в UTC, а не в местном времени |
| Значение `TIMETZ` потеряло смещение, а значение `BIT` или `BIGNUM` выглядит как байты | Эти типы нельзя отличить от обычных значений на пути в DuckLocal. `CAST(column AS VARCHAR)` в SQL покажет настоящее значение |
| Сортировка не добавляет строки за пределами предпросмотра | Сортировка по заголовку лишь переставляет загруженные строки. Используйте `ORDER BY` в SQL, чтобы упорядочить полный результат до усечения |
| Запросу нужно расширение, которое не установлено | Недостающие расширения больше не скачиваются автоматически. Установите его явно на вкладке **Расширения**, затем загрузите его или повторите запрос |
| Запрос, работавший до 0.3.0, сообщает, что расширение не установлено или функции не существует | DuckLocal 0.3.0 работает на DuckDB 2.0, которая хранит установленные расширения отдельно для каждой версии. Установите их снова на вкладке **Расширения** — см. [Расширения](schema-and-history.md#extensions) |
| Простой псевдоним столбца вроде `minutes` вызывает ошибку разбора | Это ключевое слово SQL. Напишите `AS minutes` или заключите его в кавычки: `SELECT count(*) AS "minutes" FROM events` |
| Щелчок по таблице или записи истории стёр мой SQL | Такие щелчки заменяют весь буфер редактора. Используйте новую вкладку запроса для черновой работы |
| Экспорт молча заменил файл | Экспорт пишет по указанному вами пути, не спрашивая. Выберите новое имя |

## S3

| Симптом | Причина и решение |
| --- | --- |
| Учётные данные S3 забылись | Они действуют только в течение сеанса, так задумано, и открытие или смена базы данных их очищает. Настройте S3 заново |
| Настройка S3 не удаётся без сети | При первом использовании выполняется `INSTALL httpfs`, который скачивает расширение. Подключитесь один раз, и оно будет в кэше |
| Временные (STS) учётные данные отклоняются | Токен сеанса не отправляется. Используйте долгоживущие ключи — см. [S3 и httpfs](s3.md#limitations) |
| Бакет выглядит меньше, чем есть | Перечисление останавливается на 1 000 записей на уровень. Запрашивайте шаблоном, например `'s3://bucket/prefix/*.parquet'` |

## Дашборды

| Симптом | Причина и решение |
| --- | --- |
| График дашборда сообщает, что запрос должен быть только для чтения | Запрос `.dash` попытался писать (DDL, DML, `COPY`, `ATTACH`, …). Дашборды выполняют только инструкции чтения; перенесите подготовку в редактор SQL |
| Агент не увидел мои комментарии | Комментарии никуда не отправляются: агент должен их прочитать. Попросите его выполнить `ducklocal comments FILE` или «ответь на комментарии в FILE», если у него есть [официальный навык](cli.md#install-the-official-skill) |
| Ответ или правка агента не отображается | Окно следит и за спецификацией, и за `FILE.comments.json` в течение секунды. Спецификация, которая больше не проходит проверку, сохраняет последний рабочий дашборд, а причина показывается над ним; откройте **Просмотр спецификации**, чтобы увидеть файл |
| `PIVOT` в дашборде отклоняется | `PIVOT`, вложенный в `SELECT` или `WITH`, должен называть свои значения. Перечислите их: `PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue)`, или начинайте запрос с `PIVOT` |

## Внешний вид

| Симптом | Причина и решение |
| --- | --- |
| Тема сбрасывается на светлую при каждом запуске | Тема не сохраняется между запусками; язык сохраняется |
| Текст или значки слишком малы или слишком велики | Используйте кнопку **Aa** в строке заголовка или ⌘+ / ⌘− / ⌘0. См. [Размер интерфейса](settings-and-data.md#interface-size) |
| Интерфейс на неправильном языке | Используйте кнопку **EN** / **中** в строке заголовка; выбор запоминается |

## Начать заново

Чтобы очистить историю, запомненные файлы, открытые вкладки и настройки,
закройте DuckLocal и удалите каталог данных приложения:

```bash
rm -rf ~/Library/Application\ Support/DuckLocal
```

Ваши файлы данных никогда не затрагиваются — удаляются только собственные записи
DuckLocal. О том, что там хранится, см. в разделе [Настройки и данные
приложения](settings-and-data.md).
