Распространённые ошибки¶
English · Русский
Точные фиксированные сообщения приведены в кавычках кода. Там, где текст зависит от операции/ОС, указан симптом или стабильный JSON error code; это не выдуманный вывод терминала.
| Ошибка / симптом | Причина | Решение |
|---|---|---|
command not found / команда не найдена |
Другое окружение или пакет не установлен | Активируйте нужное окружение; проверьте python -m pip --version и путь команды |
| Версия установленной команды отличается от checkout 1.6.0 | Установленная копия отстаёт от исходников | Установите checkout в отдельное окружение; не выдавайте тест старой копии за тест исходников |
unsafe filesystem path |
Symlink, конфликт входа/выхода или путь за границей | Используйте новую обычную папку; /tmp на macOS — symlink, канонический путь /private/tmp |
Output already exists: |
Пример защищает результат от перезаписи | Выберите новое имя; не удаляйте пользовательский результат |
input_not_found |
Путь относительно другой рабочей папки | Перейдите в корень checkout; проверьте наличие входа без публикации его содержимого |
missing_dependency / код 69 |
Нет optional extra | Установите нужный extra тем же Python; повторите doctor --require-extra |
invalid_arguments |
Не хватает обязательного флага или значение не в диапазоне | Выполните COMMAND --help, задайте count>0, seed≥0, ratio в [0,1] |
configuration |
Нет allowlist, неверный бюджет, конфликт JDBC/component settings | Исправьте конкретный scope/число; не ослабляйте TLS или политику |
external_service |
БД/провайдер недоступен | Проверьте разрешённый endpoint, сеть, TLS, права и квоту через администратора; не печатайте secrets |
Tool arguments failed validation |
MCP-аргументы не соответствуют схеме | Используйте tools/list и типы аргументов; отклонённый payload не пересылайте |
Invalid request parameters |
Некорректный типизированный MCP запрос | Исправьте клиент/SDK и формат JSON-RPC |
Trino request failed |
Безопасно скрытая ошибка backend | Проверьте scope, доступность и бюджеты без раскрытия сообщения драйвера |
| generate вернул 1 и оставил output | Намеренный mixed/negative не прошёл валидацию | Проверьте validation_failed и отчёты expected/observed; не считайте файл успешным valid-набором. |
| validate вернул 1 | Есть нарушения контракта | Прочитайте validation_report; для negative сопоставьте ожидаемые нарушения |
io_failure / код 74 |
Нет прав, места или ошибка файловой системы | Выберите доступный каталог, проверьте диск и резерв, сохраните входы |
recovery_required |
Одобрение прервалось после публикации набора | Прочитайте agent-status; используйте только предложенный agent-recover с проверенным fingerprint |
Что делать при неизвестной ошибке¶
Остановите повторные записи. Сохраните только безопасные метаданные: версию, команду без секретов, код завершения, фазу и счётчики. Воспроизведите на вымышленных входах. Не публикуйте исходный CSV, SQL с литералами, profile/spec своего домена, .env, DSN, полный environment или необработанный traceback.
Далее: пошаговая диагностика, FAQ.
Локальная диагностика¶
Для чего это нужно¶
Проверьте окружение и маленький синтетический пример прежде, чем разбирать подключение к внешнему сервису. Так можно отличить локальную ошибку от сетевой.
Что получится в результате¶
Безопасная сводка версии и локальных возможностей без чтения credentials.
Предварительные требования¶
Открыт терминал в корне checkout, активно нужное окружение; права на временные файлы. Для чтения doctor report не нужен доступ к БД.
Пошаговое выполнение¶
Шаг 1. Сопоставьте пути и версию¶
Что сделать: Покажите путь к интерпретатору и исполняемой команде.
Где выполнить: Терминал, корень checkout.
Команда или пример:
python -c "import sys, shutil; print(sys.executable); print(shutil.which('test-data-agent'))"
test-data-agent --version
Что должно произойти: Видны пути текущего окружения и версия пакета.
Как проверить: Оба пути принадлежат ожидаемому окружению; версия соответствует checkout.
Если не получилось: Если нет, активируйте нужный venv и установите пакет туда. Не печатайте весь environment.
Шаг 2. Запустите локальные проверки¶
Что сделать: Выполните doctor; JSON-режим удобен для автоматизации.
Где выполнить: Тот же терминал.
Команда или пример:
test-data-agent doctor
test-data-agent doctor --json
Что должно произойти: Проверены базовые импорты и smoke generation.
Как проверить: Обе команды возвращают 0.
Если не получилось: Если extra не установлен, установите только нужный; необязательное отсутствие без require-extra не означает поломку базы.
Шаг 3. Проверьте нужное расширение¶
Что сделать: В примере проверяется Parquet; замените его на нужное extra из справки.
Где выполнить: Тот же терминал.
Команда или пример:
test-data-agent doctor --require-extra parquet
Что должно произойти: Проверена локальная работоспособность Parquet, включая временный round trip.
Как проверить: Код 0.
Если не получилось: Установите .[parquet]. Успех для postgres/openai не проверяет сетевой доступ или credentials.
Проверка результата¶
Если doctor проходит, а рабочий вход нет, повторите с вымышленной фикстурой из CSV-инструкции. Если она проходит, проверяйте форму входа, spec и лимиты; при БД отдельно проверяйте разрешённое подключение с администратором.
Типичные ошибки¶
| Ошибка | Причина | Решение |
|---|---|---|
| doctor прошёл, сервис недоступен | Doctor намеренно офлайн | Проверьте сеть/роль/квоту в согласованном сервисном сценарии. |
| Код 70 | Внутренняя ошибка | Составьте минимальный синтетический reproducer; debug не публикуйте без review. |
После прерванного одобрения¶
Выполните test-data-agent agent-status out/ru-agent --json. Если фаза recovery_required, проверьте сохранённые spec/manifest и выполните точную next action из статуса с одобренным SHA-256. agent-recover перепроверяет имеющийся набор и дописывает completion metadata; он не генерирует строки заново. Этот сценарий не воспроизводился вручную в аудите; код и focused tests существуют. Не используйте recover для произвольной повреждённой папки.
Следующий шаг¶
Вопросы и ответы¶
Нужен ли AI? Нет. Демо, CSV, DatasetSpec, детерминированная генерация и валидация работают без provider.
Нужна ли база? Нет. Начните с вымышленного CSV. База — отдельный read-only источник метаданных.
Чем генерация отличается от обезличивания? Генератор создаёт новые значения. Он не переписывает каждую исходную строку и не сохраняет карту исходный ID → новый ID.
Можно ли считать синтетический набор анонимным? Автоматически нельзя. Проверьте spec, разрешённые литералы, редкие комбинации и политику назначения. Система не даёт сертификата статистической анонимности.
Почему статус стал другим после правки spec? Approval относится к точному fingerprint. После правки нужен новый review; старый отпечаток не одобряет новый файл.
Почему один seed не дал прежние байты на другой машине? Помимо seed важны вход, spec и порядок entities в нём, count, mode, locale, версия проекта, зависимости и сериализатор. Сравнивайте в одинаковом записанном окружении.
Где результат? У generate-from-csv --output — файл с соседними артефактами; у generate из spec — папка набора. Manifest указывает условия генерации. См. форматы.
Что означает validation passed? Только выполнение включённых проверок по данному spec. Не доказано, что сам spec описывает все нужные свойства.
Можно ли использовать реальные status? В синтетической генерации — только через отдельный field-scoped local-category после review нечувствительного ограниченного enum и content checks. Разрешение не распространяется на ID, текст, PII, строки или внешний AI. Сохранение ячеек один к одному относится к отдельной mixed-origin трансформации с policy и local receipt; см. ниже.
Можно ли сделать JOIN в profile-query? Нет. Поддерживается ограниченное чтение одной таблицы; не добавляйте обход через unrestricted SQL.
Можно ли импортировать SQL? Проект создаёт SQL-файл. Выполнение — отдельная операция записи в согласованную одноразовую БД с человеческим review. В этом аудите SQL не исполнялся.
Что такое selective transformation? Отдельный публичный opt-in workflow 1.6.0 с policy, snapshot digest и mixed-origin output. CLI и MCP consumers существуют; preservation требует точного локального подтверждения человеком, которое агент выдать не может. См. инструкцию.
Как повторить пример? Используйте новую папку, тот же вход, параметры и окружение. Не применяйте overwrite или удаление предыдущих результатов без необходимости.
Далее: ограничения.