Troubleshooting — Диагностика проблем

Авторизация

401 — Невалидный токен

• Симптом: API возвращает «Missing authorization» или дашборд показывает «Unauthorized»
• Причины: Токен отсутствует, истёк (TTL 24 часа) или неверный формат заголовка
• Решение: Перелогинься. Для SSE/WebSocket токен передаётся через ?token=. JWT обновляется каждые 24 часа

401 — Email не верифицирован

• Симптом: Логин успешен, но возвращает requires_verification: true
• Причины: Не нажата ссылка в письме верификации (TTL 24 часа)
• Решение: Проверь email, нажми ссылку. Или попроси администратора верифицировать вручную. OAuth-пользователи верифицируются автоматически

403 — Нет доступа к проекту

• Симптом: Операции с файлами или WebSocket terminal возвращают Forbidden
• Причины: Multi-tenancy — пользователь не является владельцем проекта. Или заблокирована попытка path traversal
• Решение: Проверь ownership проекта. Интерактивный терминал доступен только admin/CEO

Воркеры и боты

Воркер не отвечает

• Симптом: Сообщение отправлено, но ответа нет
• Причины: Процесс Claude занят, tmux-сессия упала, порт занят
• Диагностика: Проверь /health или /ping в Telegram. В CRM — иконка статуса рядом с воркером
• Решение: Нажми STOP и повтори. Или перезапусти через CRM Settings → Restart

Status: «degraded»

• Симптом: Health check возвращает status: "degraded" вместо «ok»
• Причины: 3+ последовательных ошибки Claude subprocess
• Решение: Подожди — watchdog автоматически перезапустит. Или перезапусти вручную через /watchdog в Telegram

Timeout (5 минут)

• Симптом: Бот возвращает «Claude timeout (5 min limit)»
• Причины: Задача слишком сложная для одного сообщения, большие файлы
• Решение: Раздели задачу на меньшие шаги. Переключи модель на более быструю (Haiku)

Max turns reached

• Симптом: «Reached max turns» — Claude остановился после N шагов
• Причины: Задача требует больше tool calls, чем лимит (по умолчанию 20 для Developer, 10 для Consultant)
• Решение: Раздели задачу. Или увеличь max_turns через Worker Studio

Watchdog отключил бот

• Симптом: «Permanently disabled after 10 consecutive failures»
• Причины: 10 последовательных неудач (токен отсутствует, файлы удалены, порт занят)
• Решение: Устрани первопричину, затем перезапусти через Master Bot /deploy или CRM Restart

Semantic search / RAG (Phase 71)

arc kb search возвращает пустой результат для свежего проекта

• Симптом: новый проект без wiki/issues — поиск возвращает No content found...
• Причина: RAG hooks (Phase 71.5) re-embed-ят контент на write, но до первых записей индекс пуст. CLI fallback на keyword search по wiki/tree тоже ничего не находит.
• Решение: допиши что-нибудь в wiki/issue/skill — embedding ляжет через 1–2 секунды. Или форс через arc memory refresh (re-embed MANIFEST + ROADMAP + все wiki-файлы).

Cohere 401 Unauthorized

• Симптом: в логах мастера [rag-hook] ... failed: Cohere auth rejected (401)
• Причина: COHERE_API_KEY в vault истёк или был ротирован некорректно.
• Решение: Platform Settings → RAG / Semantic search → Rotate. Live-кнопка Test проверит уже новый ключ через /v2/embed.

Cohere 429 Rate Limited

• Симптом: Backfill или hooks падают с 429.
• Причина: Trial-tier Cohere key имеет лимит 1000 calls/month; на проде нужен Production tier.
• Решение: апгрейд на https://dashboard.cohere.com/billing. Первый прод-backfill 2026-06-05 сгорел именно на этом — после перехода на Production цикл из 178 docs прошёл с 0/178 errors.

Latency tail >500ms

• Симптом: отдельные search-запросы возвращаются медленно.
• Причина: Cohere upstream tail variance — наша p50 ~195ms steady, но отдельные вызовы /v2/embed могут занимать 800–1000ms.
• Решение: см. docs/architecture/PHASE_71_SOAK_2026-06-05.md — это задокументированное upstream-ограничение, не наш код. Будущие фазы: query-embed LRU cache, Cohere region pinning.

Frontend и соединение

WebSocket отключается

• Симптом: Terminal или чат отключается с кодом 1008
• Причины: JWT-токен истёк во время сессии (TTL 24 часа)
• Решение: Обнови страницу (F5) — токен обновится автоматически

SSE-стриминг не работает

• Симптом: Ответ воркера не появляется в реальном времени
• Причины: Проект не найден в реестре или включена буферизация в nginx
• Решение: Проверь имя проекта. SSE требует proxy_buffering off в nginx

CORS-ошибка

• Симптом: Консоль браузера показывает CORS blocked
• Причины: Origin не в whitelist CRM_ALLOWED_ORIGINS
• Решение: Добавь origin в переменную CRM_ALLOWED_ORIGINS и перезапусти Master Bot

Сообщение обрезается

• Симптом: Ответ в Telegram обрывается
• Причины: Лимит Telegram — 4096 символов
• Решение: Бот автоматически делит на части [1/3] [2/3] [3/3]. Если нет — баг в split logic

База данных

«Database not initialized»

• Симптом: Бот падает с ошибкой «Database not initialized. Call initDb() first.»
• Причины: initDb() не был вызван до первого запроса, или файл БД удалён
• Решение: Перезапусти Master Bot — он автоматически инициализирует БД и прогонит миграции

«Database locked»

• Симптом: Случайные 500-ошибки при высокой нагрузке
• Причины: SQLite пишется одновременно из нескольких процессов
• Решение: WAL mode включён по умолчанию. Перезапусти зависшие процессы

Быстрая справка

Полезные команды для диагностики

# Health checks
curl -s http://localhost:19210/api/master/health | jq .
curl -s http://localhost:19211/api/child/health | jq .

# Проверка tmux-сессий
tmux list-sessions

# Логи Master Bot
tmux capture-pane -t citadel-master -p | tail -20

# Логи Child Bot
tmux capture-pane -t ws-arc-v2 -p | tail -20

# Проверка портов
ss -tlnp | grep '192[0-9][0-9]'

# Состояние базы данных
sqlite3 data/citadel.db "PRAGMA integrity_check;"

Doc enforcement (Phase 49.1+)

git push блокируется с «doc-coverage check failed»

Pre-push hook требует обновления docs при изменении кода. STDERR покажет, какие именно файлы нужно обновить.

Быстрые решения:

• Авто-черновик: arc wrapup --generate → заполни TODO → commit
• Вручную: смотри маппинг в CLAUDE.md (Documentation Law)
• Экстренный обход: git push --no-verify (оставляет след в git log)

Hook не запускается на новом клоне

bash scripts/setup-hooks.sh   # один раз на клон
git config core.hooksPath     # убедись, что = ".githooks"

GitHub Integration (Phase 49.3)

Webhook возвращает 401

• Content-Type: application/json в GitHub webhook (не form-urlencoded)
• Secret должен совпадать с выводом arc github link
• Утерял secret → удали webhook в GitHub UI + arc github unlink, создай новый

Sidebar GitHub feed пустой

• ContextRail виден при viewport ≥1280px
• Жёсткое обновление (Ctrl+Shift+R)
• Проверка БД: sqlite3 data/citadel.db "SELECT COUNT(*) FROM github_events WHERE project_name='<name>';"

Rate limit «429 Rate limited»

Кап = 100 req/min/project. Повысь в shared/routes/github.ts:RATE_MAX.

Подробнее: GitHub Integration Setup.