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

Авторизація

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

• Симптом: API повертає "Missing authorization" або dashboard показує "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 ніж ліміт (default 20 для Developer, 10 для Consultant)
• Рішення: Розбити задачу. Або збільшити max_turns через Worker Studio

Watchdog disabled bot

• Симптом: "Permanently disabled after 10 consecutive failures"
• Причини: 10 послідовних невдач (токен відсутній, файли видалені, порт зайнятий)
• Рішення: Виправити root cause, потім перезапустити через 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 cap; на проді треба 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 buffering увімкнений
• Рішення: Перевірити назву проєкту. 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() не було викликано до першого запиту, або файл DB видалено
• Рішення: Перезапустити Master Bot — він автоматично ініціалізує DB і прогоняє міграції

"Database locked"

• Симптом: Випадкові 500 помилки при високому навантаженні
• Причини: SQLite пишеться одночасно з декількох процесів
• Рішення: WAL mode увімкнений за замовчуванням. Перезапустити stale processes

Швидка довідка

Корисні команди для діагностики

# 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 коли змінюється code. STDERR покаже які саме файли треба оновити.

Швидкі рішення:

• Auto-draft: arc wrapup --generate → заповнити TODO → commit
• Manual: дивись mapping у CLAUDE.md (Documentation Law)
• Emergency bypass: git push --no-verify (залишає слід у git log)

Hook не запускається на новому clone

bash scripts/setup-hooks.sh   # one-time per clone
git config core.hooksPath     # перевір що = ".githooks"

GitHub Integration (Phase 49.3)

Webhook returns 401

• Content-Type: application/json у GitHub webhook (не form-urlencoded)
• Secret має збігатися з output arc github link
• Загублено secret → видали webhook у GitHub UI + arc github unlink, створи новий

Sidebar GitHub feed пустий

• ContextRail видимий ≥1280px viewport
• Hard refresh (Ctrl+Shift+R)
• DB check: sqlite3 data/citadel.db "SELECT COUNT(*) FROM github_events WHERE project_name='<name>';"

Rate limit "429 Rate limited"

Cap = 100 req/min/project. Підвищ у shared/routes/github.ts:RATE_MAX.

Детальніше: GitHub Integration Setup.