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

NotebookLM Bridge

Semantische Suche funktioniert nicht

Symptom: arc kb search oder NotebookLM-Tab gibt einen Fehler zurück
Diagnose: /health prüfen — ob google_auth: true
Ursachen: Google-Authentifizierung abgelaufen, Bridge-Service nicht gestartet
Lösung: Bridge-Service neu starten. Google-Auth erneuern

Veraltete Daten in der Suche

Symptom: Suche gibt veraltete Informationen zurück
Ursachen: Cache (TTL 5 Minuten) oder Quellen nicht synchronisiert
Lösung: arc memory refresh ausführen für vollständige Neusynchronisierung

Synchronisierungswarteschlange überfüllt (429)

Symptom: Sync gibt HTTP 429 zurück
Ursachen: Mehr als 200 Einträge in der Warteschlange
Lösung: 2-3 Minuten warten — die Warteschlange wird mit 1 Element pro 2 Sekunden abgearbeitet

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.