Troubleshooting — Problemdiagnose

Authentifizierung

401 — Ungültiger Token

Symptom: API gibt „Missing authorization" zurück oder Dashboard zeigt „Unauthorized"
Ursachen: Token fehlt, ist abgelaufen (TTL 24 Stunden) oder Header-Format ist falsch
Lösung: Erneut einloggen. Für SSE/WebSocket wird der Token via ?token= übergeben. JWT wird alle 24 Stunden erneuert

401 — E-Mail nicht verifiziert

Symptom: Login erfolgreich, aber Antwort enthält requires_verification: true
Ursachen: Verifizierungslink in der E-Mail wurde nicht geklickt (TTL 24 Stunden)
Lösung: E-Mail prüfen und den Link anklicken. Oder Admin bitten, die Verifizierung manuell durchzuführen. OAuth-Nutzer werden automatisch verifiziert

403 — Kein Zugriff auf das Projekt

Symptom: Dateioperationen oder WebSocket-Terminal geben Forbidden zurück
Ursachen: Multi-Tenancy — der Nutzer ist nicht Eigentümer des Projekts. Oder ein Path-Traversal-Versuch wurde blockiert
Lösung: Projekteigentümerschaft prüfen. Interaktives Terminal ist nur für admin/CEO verfügbar

Worker und Bots

Worker antwortet nicht

Symptom: Nachricht wurde gesendet, aber keine Antwort
Ursachen: Claude-Prozess ist beschäftigt, tmux-Sitzung ist abgestürzt, Port ist belegt
Diagnose: /health oder /ping in Telegram prüfen. Im CRM — Status-Icon neben dem Worker
Lösung: STOP drücken und erneut versuchen. Oder über CRM Settings → Restart neu starten

Status: „degraded"

Symptom: Health Check gibt status: "degraded" statt „ok" zurück
Ursachen: 3+ aufeinanderfolgende Claude-Subprocess-Fehler
Lösung: Warten — Watchdog startet automatisch neu. Oder manuell über /watchdog in Telegram neu starten

Timeout (5 Minuten)

Symptom: Bot gibt „Claude timeout (5 min limit)" zurück
Ursachen: Aufgabe ist für eine einzelne Nachricht zu komplex, große Dateien
Lösung: Aufgabe in kleinere Schritte aufteilen. Modell auf ein schnelleres (Haiku) umstellen

Max turns reached

Symptom: „Reached max turns" — Claude hat nach N Schritten gestoppt
Ursachen: Aufgabe erfordert mehr Tool Calls als das Limit (standardmäßig 20 für Developer, 10 für Consultant)
Lösung: Aufgabe aufteilen. Oder max_turns über Worker Studio erhöhen

Watchdog hat Bot deaktiviert

Symptom: „Permanently disabled after 10 consecutive failures"
Ursachen: 10 aufeinanderfolgende Fehler (Token fehlt, Dateien gelöscht, Port belegt)
Lösung: Root Cause beheben, dann über Master Bot /deploy oder CRM Restart neu starten

Semantic search / RAG (Phase 71)

`arc kb search` liefert ein leeres Ergebnis für ein frisches Projekt

Symptom: neues Projekt ohne Wiki/Issues — die Suche gibt No content found... zurück
Ursache: RAG-Hooks (Phase 71.5) re-embedden Inhalte beim Schreiben, aber vor den ersten Einträgen ist der Index leer. Der CLI-Fallback auf Keyword-Suche über Wiki/Tree findet ebenfalls nichts.
Lösung: etwas ins Wiki/Issue/Skill schreiben — das Embedding landet nach 1-2 Sekunden. Oder per arc memory refresh erzwingen (Re-Embed von MANIFEST + ROADMAP + allen Wiki-Dateien).

Cohere 401 Unauthorized

Symptom: in den Master-Logs [rag-hook] ... failed: Cohere auth rejected (401)
Ursache: COHERE_API_KEY im Vault ist abgelaufen oder wurde inkorrekt rotiert.
Lösung: Platform Settings → RAG / Semantic search → Rotate. Der Live-Test-Button prüft den neuen Key direkt über /v2/embed.

Cohere 429 Rate Limited

Symptom: Backfill oder Hooks schlagen mit 429 fehl.
Ursache: Ein Trial-Tier-Cohere-Key hat ein Cap von 1000 Calls/Monat; in Produktion ist der Production-Tier nötig.
Lösung: Upgrade unter https://dashboard.cohere.com/billing. Der erste Prod-Backfill am 2026-06-05 ist genau daran gescheitert — nach dem Wechsel auf Production lief der Zyklus über 178 Docs mit 0/178 Fehlern durch.

Latency-Tail >500ms

Symptom: einzelne Suchanfragen kommen langsam zurück.
Ursache: Cohere-Upstream-Tail-Varianz — unsere p50 liegt stabil bei ~195ms, aber einzelne /v2/embed-Calls können 800-1000ms dauern.
Lösung: docs/architecture/PHASE_71_SOAK_2026-06-05.md prüfen — das ist eine dokumentierte Upstream-Limitierung, nicht unser Code. Künftige Phasen: Query-Embed-LRU-Cache, Cohere Region Pinning.

Frontend und Verbindungen

WebSocket trennt die Verbindung

Symptom: Terminal oder Chat trennt mit Code 1008
Ursachen: JWT-Token ist während der Sitzung abgelaufen (TTL 24 Stunden)
Lösung: Seite neu laden (F5) — Token wird automatisch erneuert

SSE-Streaming funktioniert nicht

Symptom: Worker-Antwort erscheint nicht in Echtzeit
Ursachen: Projekt nicht in der Registry gefunden, oder nginx-Buffering ist aktiviert
Lösung: Projektnamen prüfen. SSE erfordert proxy_buffering off in nginx

CORS-Fehler

Symptom: Browser-Konsole zeigt CORS blocked
Ursachen: Origin ist nicht in der Whitelist von CRM_ALLOWED_ORIGINS
Lösung: Origin zur Variable CRM_ALLOWED_ORIGINS hinzufügen und Master Bot neu starten

Nachricht wird abgeschnitten

Symptom: Antwort in Telegram bricht ab
Ursachen: Telegram-Limit von 4096 Zeichen
Lösung: Bot teilt automatisch in Teile auf [1/3] [2/3] [3/3]. Wenn nicht — Bug in der Split-Logik

Datenbank

„Database not initialized"

Symptom: Bot stürzt mit „Database not initialized. Call initDb() first." ab
Ursachen: initDb() wurde vor der ersten Anfrage nicht aufgerufen, oder DB-Datei wurde gelöscht
Lösung: Master Bot neu starten — er initialisiert die DB automatisch und führt Migrationen durch

„Database locked"

Symptom: Zufällige 500-Fehler bei hoher Last
Ursachen: SQLite wird gleichzeitig von mehreren Prozessen geschrieben
Lösung: WAL-Mode ist standardmäßig aktiviert. Veraltete Prozesse neu starten

Kurzübersicht

Problem	Zuerst prüfen	Schnelle Lösung
Bot antwortet nicht	`/health` oder `/ping`	Restart über CRM
401 Unauthorized	Token-Erstellungszeit	Erneut einloggen
403 Forbidden	Projekteigentümerschaft	owner_id prüfen
Degraded status	`consecutiveFailures`	Watchdog abwarten
Timeout 5m	Aufgabenkomplexität	In kleinere Schritte aufteilen
Bridge-Fehler	`google_auth` in /health	`arc memory refresh`
CORS blocked	CRM_ALLOWED_ORIGINS	Origin hinzufügen
WebSocket disconnect	JWT-Lebensdauer (24h)	Seite neu laden

Nützliche Diagnosebefehle

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

# tmux-Sitzungen prüfen
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

# Ports prüfen
ss -tlnp | grep '192[0-9][0-9]'

# Datenbankzustand
sqlite3 data/citadel.db "PRAGMA integrity_check;"

Doc enforcement (Phase 49.1+)

`git push` wird mit „doc-coverage check failed" blockiert

Der Pre-Push-Hook erfordert Docs-Updates, wenn Code geändert wird. STDERR zeigt genau an, welche Dateien aktualisiert werden müssen.

Schnelle Lösungen:

Auto-Draft: arc wrapup --generate → TODOs ausfüllen → commit
Manuell: Mapping in CLAUDE.md nachschlagen (Documentation Law)
Notfall-Bypass: git push --no-verify (hinterlässt Spuren im git log)

Hook startet nicht bei neuem Clone

bash scripts/setup-hooks.sh   # einmalig pro Clone
git config core.hooksPath     # prüfen, ob = ".githooks"

GitHub Integration (Phase 49.3)

Webhook gibt 401 zurück

Content-Type: application/json im GitHub-Webhook (nicht form-urlencoded)
Secret muss mit der Ausgabe von arc github link übereinstimmen
Secret verloren? → Webhook in GitHub UI löschen + arc github unlink, neu erstellen

GitHub-Feed in der Sidebar ist leer

ContextRail sichtbar ab ≥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/Projekt. In shared/routes/github.ts:RATE_MAX erhöhen.

Mehr dazu: GitHub Integration Setup.