Troubleshooting

Каноничный порядок bootstrap и включения расписаний описан в docs/operations/deployment.md (раздел Каноничный порядок заполнения таблиц (bootstrap + schedules)). При инцидентах с пустыми таблицами/аномальным quarantine сверяйтесь в первую очередь с этим runbook.

Worker не стартует

Проверьте:

docker compose ps
docker compose logs --tail=200 worker

Не запускается SyncExchangesWorkflow

Проверьте регистрацию workflow и доступность CoinGecko:

docker compose exec -T temporal-admin-tools temporal workflow start \
  --address temporal:7233 --namespace default --task-queue default \
  --type SyncExchangesWorkflow --workflow-id sync-exchanges-debug-$(date +%s)

Не запускается SyncNetworksCatalogWorkflow

Проверьте регистрацию workflow, доступность CoinGecko/chainid.network/DefiLlama и ручной запуск:

docker compose exec -T temporal-admin-tools temporal workflow start \
  --address temporal:7233 --namespace default --task-queue default \
  --type SyncNetworksCatalogWorkflow \
  --workflow-id sync-networks-catalog-debug-$(date +%s) \
  --input '{"force_full_refresh":false,"soft_delete_grace_days":30,"metrics_required":false}'

Проблемы с BingX scraping

Проверьте наличие Playwright браузера в контейнере/окружении и логи: - ScrapeBingXLaunchpoolWorkflow / SyncBingXLaunchpoolWorkflow - ScrapeBingXXPoolWorkflow / SyncBingXXPoolWorkflow

Ручной запуск ingestion workflow:

docker compose exec -T temporal-admin-tools temporal workflow start \
  --address temporal:7233 --namespace default --task-queue default \
  --type SyncBingXLaunchpoolWorkflow \
  --workflow-id sync-bingx-launchpool-debug-$(date +%s) \
  --input '{"include_details":true}'

Ручной запуск BingX XPool ingestion workflow:

docker compose exec -T temporal-admin-tools temporal workflow start \
  --address temporal:7233 --namespace default --task-queue default \
  --type SyncBingXXPoolWorkflow \
  --workflow-id sync-bingx-xpool-debug-$(date +%s) \
  --input '{"include_details":true}'

Проблемы с Bitget / Bybit / KuCoin earn-style pipelines

Для SyncBitgetLaunchpoolWorkflow, SyncBybitLaunchpoolWorkflow, SyncBybitEasyEarnWorkflow, SyncKuCoinLaunchpoolWorkflow, SyncKuCoinEarnWorkflow сначала проверьте регистрацию workflow и ручной запуск с минимальным input.

Примеры:

docker compose exec -T temporal-admin-tools temporal workflow start \
  --address temporal:7233 --namespace default --task-queue default \
  --type SyncBitgetLaunchpoolWorkflow \
  --workflow-id sync-bitget-launchpool-debug-$(date +%s) \
  --input '{"include_details":true}'

docker compose exec -T temporal-admin-tools temporal workflow start \
  --address temporal:7233 --namespace default --task-queue default \
  --type SyncKuCoinLaunchpoolWorkflow \
  --workflow-id sync-kucoin-launchpool-debug-$(date +%s) \
  --input '{"include_current":true,"include_history":true}'

Если run падает с *_access_denied, это non-retryable upstream/network problem: проверяйте доступность endpoint, блокировки по IP/ASN и override переменные *_BASE_URL.

Не запускается SyncExchangeCoinsWorkflow

Проверьте регистрацию workflow, а также ручной запуск:

docker compose exec -T temporal-admin-tools temporal workflow start \
  --address temporal:7233 --namespace default --task-queue default \
  --type SyncExchangeCoinsWorkflow \
  --workflow-id sync-exchange-coins-debug-$(date +%s) \
  --input '{"force_full_refresh":false,"soft_delete_grace_days":30}'

Приватные биржи помечаются skipped

Для Bybit/Binance/BingX/OKX/MEXC нужны ключи в env (*_API_KEY, *_API_SECRET, для OKX также OKX_API_PASSPHRASE). Если ключей нет, run не падает, но в asset_mapping_quarantine появится причина missing_credentials. Для KuCoin (как и для Gate/Bitget) ключи не требуются: используется public endpoint.

Много записей в `asset_mapping_quarantine`

Частые причины: - missing_network_mapping — локальная сеть биржи не сопоставилась с networks_catalog.network_key; - missing_contract — у актива нет контрактного адреса, conservative mapping не склеивает такие активы автоматически; - api_error — upstream API вернул ошибку, биржа обработана в partial failure режиме.

Не запускается SyncGateLaunchpoolWorkflow

Проверьте регистрацию workflow и ручной запуск:

docker compose exec -T temporal-admin-tools temporal workflow start \
  --address temporal:7233 --namespace default --task-queue default \
  --type SyncGateLaunchpoolWorkflow \
  --workflow-id sync-gate-launchpool-debug-$(date +%s) \
  --input '{"page":1,"page_size":1000,"status":0}'

`gate_access_denied` в Gate Launchpool

gate_access_denied считается fatal ошибкой: workflow run падает и не переводится в skip/quarantine-only режим.

Проверьте: - доступность https://www.gate.com/apiw/v2/earn/launch-pool/project-list; - наличие блокировок по IP/ASN; - что endpoint не блокируется на вашей сети (в коде используется hardcoded URL Gate).

Диагностика последних падений:

docker compose logs --tail=300 worker | rg -in "gate_access_denied|launchpool"

Не запускаются SDK loans workflows

Для SyncGateLoansWorkflow, SyncBybitLoansWorkflow, SyncKuCoinLoansWorkflow, SyncWhitebitLoansWorkflow проверьте:

что worker стартовал и зарегистрировал workflow;
что для private SDK surfaces заданы нужные credentials в .env;
что upstream base URL не переопределен в невалидное значение.

Быстрый smoke run:

docker compose exec -T temporal-admin-tools temporal workflow start \
  --address temporal:7233 --namespace default --task-queue default \
  --type SyncBybitLoansWorkflow \
  --workflow-id sync-bybit-loans-debug-$(date +%s) \
  --input '{}'

Для KuCoin и WhiteBIT отдельно проверьте KUCOIN_API_KEY / KUCOIN_API_SECRET / KUCOIN_API_PASSPHRASE и WHITEBIT_API_KEY / WHITEBIT_API_SECRET.

Terry ingestion schedule не появляется

Auto-upsert paused schedule для Terry выполняется только если у worker задан TERRY_DEFAULT_DATA_SOURCE_ID.

Проверьте:

переменная содержит валидный UUID;
worker стартовал без ошибок;
при старте нет ошибки EnsureRunIngestionScheduleWorkflow в логах.

Ручной upsert schedule:

docker compose exec -T temporal-admin-tools temporal workflow start \
  --address temporal:7233 --namespace default --task-queue default \
  --type EnsureRunIngestionScheduleWorkflow \
  --workflow-id ensure-run-ingestion-schedule-debug-$(date +%s) \
  --input '{"schedule_id":"run-ingestion","cron":"0 0 * * *","timezone":"UTC","task_queue":"default","data_source_id":"<uuid>","paused":true,"preserve_paused_state":true}'

Просмотр расписаний:

docker compose exec -T temporal-admin-tools temporal schedule list --address temporal:7233 --namespace default

RunIngestionWorkflow падает сразу

Частые причины:

data_source_id не существует в terry.data_sources;
источник неактивен;
current_loader_config_id отсутствует или активная версия config не в статусе active;
loader fetcher/middleware для выбранного source.type ещё не реализованы.

Для диагностики смотрите worker логи и проверяйте catalog записи в terry.workspaces, terry.domains, terry.data_sources, terry.loader_configs.

После squashed migrations сервис падает на migration

Проект поддерживает только fresh-install:

docker compose down -v
docker compose up -d

Старые БД/данные до squash не поддерживаются.