Dépannage — Diagnostic des problèmes

Authentification

401 — Token invalide

Symptôme : L'API retourne "Missing authorization" ou le tableau de bord affiche "Unauthorized"
Causes : Token absent, expiré (TTL 24 heures), ou format d'en-tête incorrect
Solution : Se reconnecter. Pour SSE/WebSocket le token est passé via ?token=. Le JWT est renouvelé toutes les 24 heures

401 — Email non vérifié

Symptôme : Login réussi, mais retourne requires_verification: true
Causes : Le lien dans l'email de vérification n'a pas été cliqué (TTL 24 heures)
Solution : Vérifier l'email, cliquer le lien. Ou demander à un admin de vérifier manuellement. Les utilisateurs OAuth sont vérifiés automatiquement

403 — Pas d'accès au projet

Symptôme : Les opérations fichiers ou le terminal WebSocket retournent Forbidden
Causes : Multi-tenancy — l'utilisateur n'est pas propriétaire du projet. Ou tentative de path traversal bloquée
Solution : Vérifier la propriété du projet. Le terminal interactif est uniquement accessible admin/CEO

Workers et bots

Le worker ne répond pas

Symptôme : Message envoyé, mais pas de réponse
Causes : Processus Claude occupé, session tmux tombée, port occupé
Diagnostic : Vérifier /health ou /ping dans Telegram. Dans le CRM — icône de statut à côté du worker
Solution : Cliquer STOP et réessayer. Ou redémarrer via CRM Paramètres → Restart

Status: "degraded"

Symptôme : Le health check retourne status: "degraded" au lieu de "ok"
Causes : 3+ erreurs consécutives du subprocess Claude
Solution : Attendre — le watchdog redémarrera automatiquement. Ou redémarrer manuellement via /watchdog dans Telegram

Timeout (5 minutes)

Symptôme : Le bot retourne "Claude timeout (5 min limit)"
Causes : Tâche trop complexe pour un seul message, fichiers volumineux
Solution : Décomposer la tâche en étapes plus petites. Changer le modèle pour un plus rapide (Haiku)

Max turns reached

Symptôme : "Reached max turns" — Claude s'est arrêté après N étapes
Causes : La tâche nécessite plus de tool calls que la limite (défaut 20 pour Developer, 10 pour Consultant)
Solution : Décomposer la tâche. Ou augmenter max_turns via Worker Studio

Watchdog a désactivé le bot

Symptôme : "Permanently disabled after 10 consecutive failures"
Causes : 10 échecs consécutifs (token absent, fichiers supprimés, port occupé)
Solution : Corriger la cause racine, puis redémarrer via Master Bot /deploy ou CRM Restart

Recherche sémantique / RAG (Phase 71)

`arc kb search` retourne un résultat vide pour un projet tout neuf

Symptôme : nouveau projet sans wiki/issues — la recherche retourne No content found...
Cause : les RAG hooks (Phase 71.5) ré-embeddent le contenu à l'écriture, mais avant les premières entrées l'index est vide. Le fallback CLI sur la recherche par mots-clés dans wiki/tree ne trouve rien non plus.
Solution : écrire quelque chose dans un wiki/issue/skill — l'embedding arrive en 1-2 secondes. Ou forcer via arc memory refresh (ré-embed MANIFEST + ROADMAP + tous les fichiers wiki).

Cohere 401 Unauthorized

Symptôme : dans les logs du master [rag-hook] ... failed: Cohere auth rejected (401)
Cause : la COHERE_API_KEY dans le vault a expiré ou a été mal rotée.
Solution : Platform Settings → RAG / Semantic search → Rotate. Le bouton live Test valide la nouvelle clé via /v2/embed.

Cohere 429 Rate Limited

Symptôme : le backfill ou les hooks échouent avec un 429.
Cause : une clé Cohere trial est plafonnée à 1000 calls/month ; en prod il faut le tier Production.
Solution : upgrade sur https://dashboard.cohere.com/billing. Le premier backfill prod du 2026-06-05 a buté exactement là-dessus — après passage en Production, le cycle de 178 docs est passé avec 0/178 erreurs.

Latence en queue de distribution >500ms

Symptôme : certaines requêtes de recherche reviennent lentement.
Cause : variance de latence côté Cohere upstream — notre p50 est stable à ~195ms, mais certains appels /v2/embed peuvent prendre 800-1000ms.
Solution : consulter docs/architecture/PHASE_71_SOAK_2026-06-05.md — c'est une limite upstream documentée, pas notre code. Phases futures : cache LRU des query-embeds, region pinning Cohere.

Frontend et connexions

WebSocket se déconnecte

Symptôme : Le terminal ou le chat se déconnecte avec le code 1008
Causes : Le token JWT a expiré pendant la session (TTL 24 heures)
Solution : Rafraîchir la page (F5) — le token se renouvellera automatiquement

Le streaming SSE ne fonctionne pas

Symptôme : La réponse du worker n'apparaît pas en temps réel
Causes : Projet introuvable dans le registre, ou buffering nginx activé
Solution : Vérifier le nom du projet. SSE nécessite proxy_buffering off dans nginx

Erreur CORS

Symptôme : La console du navigateur affiche CORS blocked
Causes : Origin absent de la liste blanche CRM_ALLOWED_ORIGINS
Solution : Ajouter l'origin dans la variable CRM_ALLOWED_ORIGINS et redémarrer le Master Bot

Message tronqué

Symptôme : La réponse dans Telegram est coupée
Causes : Limite Telegram de 4 096 caractères
Solution : Le bot divise automatiquement en parties [1/3] [2/3] [3/3]. Si non — bug dans la logique de split

Base de données

"Database not initialized"

Symptôme : Le bot plante avec l'erreur "Database not initialized. Call initDb() first."
Causes : initDb() n'a pas été appelé avant la première requête, ou le fichier DB a été supprimé
Solution : Redémarrer le Master Bot — il initialise automatiquement la DB et exécute les migrations

"Database locked"

Symptôme : Erreurs 500 aléatoires sous charge élevée
Causes : SQLite écrit simultanément depuis plusieurs processus
Solution : Le mode WAL est activé par défaut. Redémarrer les processus obsolètes

Référence rapide

Problème	Première chose à vérifier	Solution rapide
Bot ne répond pas	`/health` ou `/ping`	Restart via CRM
401 Unauthorized	Heure de création du token	Se reconnecter
403 Forbidden	Propriété du projet	Vérifier owner_id
Status degraded	`consecutiveFailures`	Attendre le watchdog
Timeout 5m	Complexité de la tâche	Décomposer en étapes
Erreur Bridge	`google_auth` dans /health	`arc memory refresh`
CORS blocked	CRM_ALLOWED_ORIGINS	Ajouter l'origin
WebSocket disconnect	Durée de vie JWT (24h)	Rafraîchir la page

Commandes utiles pour le diagnostic

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

# Vérification des sessions tmux
tmux list-sessions

# Logs du Master Bot
tmux capture-pane -t citadel-master -p | tail -20

# Logs du Child Bot
tmux capture-pane -t ws-arc-v2 -p | tail -20

# Vérification des ports
ss -tlnp | grep '192[0-9][0-9]'

# État de la base de données
sqlite3 data/citadel.db "PRAGMA integrity_check;"

Application des docs (Phase 49.1+)

`git push` bloqué avec "doc-coverage check failed"

Le hook pre-push exige la mise à jour des docs quand le code change. STDERR indiquera quels fichiers doivent être mis à jour.

Solutions rapides :

Auto-draft : arc wrapup --generate → remplir les TODO → commit
Manuel : voir le mapping dans CLAUDE.md (Documentation Law)
Contournement d'urgence : git push --no-verify (laisse une trace dans git log)

Le hook ne se lance pas sur un nouveau clone

bash scripts/setup-hooks.sh   # une fois par clone
git config core.hooksPath     # vérifier que = ".githooks"

Intégration GitHub (Phase 49.3)

Webhook retourne 401

Content-Type: application/json dans le webhook GitHub (pas form-urlencoded)
Le secret doit correspondre à la sortie de arc github link
Secret perdu → supprimer le webhook dans l'UI GitHub + arc github unlink, en créer un nouveau

Feed GitHub de la barre latérale vide

ContextRail visible ≥1280px viewport
Rafraîchissement forcé (Ctrl+Shift+R)
Vérification DB : sqlite3 data/citadel.db "SELECT COUNT(*) FROM github_events WHERE project_name='<name>';"

Rate limit "429 Rate limited"

Cap = 100 req/min/projet. Augmenter dans shared/routes/github.ts:RATE_MAX.

Plus de détails : Configuration de l'intégration GitHub.