Dépannage — Diagnostic des problèmes

Autorisation

401 — Token invalide

Symptôme : l'API renvoie « Missing authorization » ou le dashboard affiche « Unauthorized »
Causes : Token manquant, expiré (TTL de 24 heures), ou format d'en-tête incorrect
Solution : Reconnecte-toi. Pour SSE/WebSocket, le token est passé via ?token=. Le JWT est renouvelé toutes les 24 heures

401 — Email non vérifié

Symptôme : Le login réussit mais renvoie requires_verification: true
Causes : Le lien dans l'email de vérification n'a pas été cliqué (TTL de 24 heures)
Solution : Vérifie l'email et clique sur le lien. Ou demande à 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 sur les fichiers ou le terminal WebSocket renvoient Forbidden
Causes : Multi-tenancy — l'utilisateur n'est pas le propriétaire du projet. Ou une tentative de path traversal a été bloquée
Solution : Vérifie la propriété du projet. Le terminal interactif n'est disponible que pour admin/CEO

Workers et bots

Le worker ne répond pas

Symptôme : Un message a été envoyé mais il n'y a pas de réponse
Causes : Le processus Claude est occupé, la session tmux a planté, le port est pris
Diagnostic : Vérifie /health ou /ping dans Telegram. Dans le CRM — l'icône de statut à côté du worker
Solution : Appuie sur STOP et réessaie. Ou redémarre via CRM Settings → Restart

Statut : « degraded »

Symptôme : Le health check renvoie status: "degraded" au lieu de « ok »
Causes : 3+ erreurs consécutives du sous-processus Claude
Solution : Attends — le watchdog le redémarrera automatiquement. Ou redémarre manuellement via /watchdog dans Telegram

Timeout (5 minutes)

Symptôme : Le bot renvoie « Claude timeout (5 min limit) »
Causes : La tâche est trop complexe pour un seul message, fichiers volumineux
Solution : Découpe la tâche en étapes plus petites. Passe à un modèle plus rapide (Haiku)

Max turns atteint

Symptôme : « Reached max turns » — Claude s'est arrêté après N étapes
Causes : La tâche nécessite plus d'appels d'outils que la limite (par défaut 20 pour Developer, 10 pour Consultant)
Solution : Découpe la tâche. Ou augmente max_turns via Worker Studio

Le watchdog a désactivé le bot

Symptôme : « Permanently disabled after 10 consecutive failures »
Causes : 10 échecs consécutifs (token manquant, fichiers supprimés, port pris)
Solution : Corrige la cause racine, puis redémarre via Master Bot /deploy ou CRM Restart

Recherche sémantique / RAG (Phase 71)

`arc kb search` renvoie un résultat vide pour un projet tout frais

Symptôme : un nouveau projet sans wiki/issues — la recherche renvoie No content found...
Cause : les hooks RAG (Phase 71.5) re-embed le contenu à l'écriture, mais tant qu'il n'y a pas de première écriture, l'index est vide. Le fallback du CLI vers la recherche par mot-clé sur wiki/tree ne trouve rien non plus.
Solution : écris quelque chose dans un wiki/issue/skill — l'embedding atterrit en 1-2 secondes. Ou force-le via arc memory refresh (re-embed MANIFEST + ROADMAP + tous les fichiers wiki).

Cohere 401 Unauthorized

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

Cohere 429 Rate Limited

Symptôme : Le backfill ou les hooks échouent avec 429.
Cause : Une clé Cohere de tier trial a un plafond de 1000 appels/mois ; la production nécessite le tier Production.
Solution : passe au niveau supérieur sur https://dashboard.cohere.com/billing. Le premier backfill prod du 2026-06-05 a grillé sur exactement ça — après passage en Production, le cycle de 178 docs s'est terminé avec 0/178 erreur.

Queue de latence >500ms

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

Frontend et connectivité

Déconnexions WebSocket

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

Le streaming SSE ne fonctionne pas

Symptôme : La réponse du worker n'apparaît pas en temps réel
Causes : Le projet n'a pas été trouvé dans le registry, ou le buffering nginx est activé
Solution : Vérifie le nom du projet. SSE nécessite proxy_buffering off dans nginx

Erreur CORS

Symptôme : La console du navigateur affiche CORS blocked
Causes : L'origine n'est pas dans la whitelist CRM_ALLOWED_ORIGINS
Solution : Ajoute l'origine à la variable CRM_ALLOWED_ORIGINS et redémarre le Master Bot

Le message est coupé

Symptôme : La réponse dans Telegram est tronquée
Causes : La limite de 4096 caractères de Telegram
Solution : Le bot découpe automatiquement en parties [1/3] [2/3] [3/3]. Si ce n'est pas le cas — c'est un bug dans la logique de découpage

Base de données

« Database not initialized »

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

« Database locked »

Symptôme : Erreurs 500 aléatoires sous forte charge
Causes : SQLite est écrit par plusieurs processus à la fois
Solution : Le mode WAL est activé par défaut. Redémarre les processus périmés

Référence rapide

Problème	Première chose à vérifier	Correctif rapide
Le bot ne répond pas	`/health` ou `/ping`	Redémarrer via le CRM
401 Unauthorized	Heure de création du token	Se reconnecter
403 Forbidden	Propriété du projet	Vérifier owner_id
Statut degraded	`consecutiveFailures`	Attendre le watchdog
Timeout 5m	Complexité de la tâche	Découper en étapes plus petites
Erreur du bridge	`google_auth` dans /health	`arc memory refresh`
CORS blocked	CRM_ALLOWED_ORIGINS	Ajouter l'origine
Déconnexion WebSocket	Durée de vie du JWT (24h)	Rafraîchir la page

Commandes de diagnostic utiles

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

# Check tmux sessions
tmux list-sessions

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

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

# Check ports
ss -tlnp | grep '192[0-9][0-9]'

# Database state
sqlite3 data/citadel.db "PRAGMA integrity_check;"

Application de la doc (Phase 49.1+)

`git push` est bloqué avec « doc-coverage check failed »

Le hook pre-push exige des mises à jour de doc quand le code change. STDERR montre exactement quels fichiers doivent être mis à jour.

Correctifs rapides :

Ébauche auto : arc wrapup --generate → remplis les TODO → commit
Manuel : vois le mapping dans CLAUDE.md (Documentation Law)
Contournement d'urgence : git push --no-verify (laisse une trace dans le git log)

Le hook ne s'exécute pas sur un clone tout frais

bash scripts/setup-hooks.sh   # one-time per clone
git config core.hooksPath     # verify it equals ".githooks"

Intégration GitHub (Phase 49.3)

Le webhook renvoie 401

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

Le feed GitHub de la sidebar est vide

Le ContextRail est visible sur un viewport ≥1280px
Hard refresh (Ctrl+Shift+R)
Vérification DB : sqlite3 data/citadel.db "SELECT COUNT(*) FROM github_events WHERE project_name='<name>';"

Rate limit « 429 Rate limited »

Plafond = 100 req/min/projet. Augmente-le dans shared/routes/github.ts:RATE_MAX.

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