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

NotebookLM Bridge

Семантический поиск не работает

• Симптом: arc kb search или вкладка NotebookLM возвращает ошибку
• Диагностика: Проверь /health — должно быть google_auth: true
• Причины: Истекла авторизация Google, сервис Bridge не запущен
• Решение: Перезапусти сервис Bridge. Обнови Google auth

Устаревшие данные в поиске

• Симптом: Поиск возвращает устаревшую информацию
• Причины: Кеш (TTL 5 минут) или источники не синхронизированы
• Решение: Запусти arc memory refresh для полной пересинхронизации

Очередь синхронизации переполнена (429)

• Симптом: Sync возвращает HTTP 429
• Причины: Более 200 элементов в очереди
• Решение: Подожди 2–3 минуты — очередь обрабатывается со скоростью 1 элемент / 2 секунды

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.