Troubleshooting

Häufige Symptome, Ursache, Lösung. file:line-Referenzen und Cross-Links zu den Docs.

Start & Config

Der Server beendet sofort mit process.exit(1)

• Ursache: Env-Zod-Validierung fehlgeschlagen (src/config/env.ts).
• Fix: Prüfe die Logs - sie nennen die ungültige Variable. Prüfe JWT_SECRET (erf.), COLLECTOR_SECRET (erf.), DATABASE_URL, Ports. Vergleiche mit .env.example.

COLLECTOR_SECRET Mismatch zwischen Server und Collector

• Symptom: Der Collector kann den Dokumentstatus nicht melden; der Upload bleibt "processing".
• Fix: Setze denselben COLLECTOR_SECRET im Root-.env (Single-Config - die Per-Package-.env-Schicht wurde in v0.22 entfernt). Constant-Time-Vergleich → stiller 401.

WIDGET_API_KEY Mismatch Widget↔Server

• Symptom: Das Widget lädt die Config nicht / Chat 401 vom Server.
• Fix: Derselbe Key im Root-.env (Single-Config). Ohne Key ist der Cache-Bust-Push ein No-op (TTL 5 min).

Über die UI geänderte Config ohne Wirkung

• Ursache: ALWAYS_READONLY-Keys (JWT_SECRET, DATABASE_URL, Ports, URLs) werden von den Bulk Settings abgelehnt; andere folgen DB > ENV > Default.
• Fix: Für Readonly-Keys .env ändern + Restart. PUT /api/system/settings gibt { rejected: [...] } zurück - prüfe dieses Array.

Database

Konfliktierende Migrationen / Dev-Reset

• Fix: In Dev mit Wegwerf-DB Reset mit pnpm db:migrate:reset:guard (erfordert PRISMA_MIGRATE_RESET_CONFIRM=yes oder --force-accept-data-loss - nie in Produktion). Deploy mit Guard: pnpm db:migrate:guard (verweigert destruktive Migrationen ohne explizite Zustimmung). Prüfe PostgreSQL 16 und die korrekte DATABASE_URL.

Backup-Restore nicht atomar / partielle Daten

• Ursache: Der Restore nutzt psql --single-transaction --set ON_ERROR_STOP=on; bei Fehler macht er einen vollständigen Rollback.
• Fix: Prüfe die psql-Logs; Safety-Backup vor dem Restore (runSafetyBackup). Nutze /restore/:logId/dry-run vor dem echten Restore.

RAG & Embedding

Vector Search liefert 0 Treffer, aber FTS funktioniert

• Ursache: Guard D-01 - aktuelle EMBEDDING_MODEL ≠ embeddingModel der Document (z. B. Modell nach dem Upload gewechselt): Der Vector-Leg wird übersprungen und die Suche degradiert auf FTS-only.
• Fix: Re-Embed via POST /api/system/reembed-documents (Admin, optional workspaceId/documentIds), um die Chunks mit dem aktuellen Modell neu zu embedden; wenn nur der FTS-Index aus dem Vector DB neu aufgebaut werden soll: POST /api/system/reindex-documents. Beide admin-only, auch aus Settings → Maintenance.

RAG im Widget degradiert (status: rag-degraded)

• Ursache: RAG-Pre-Search fehlgeschlagen (Collector down, leere Workspace-Whitelist) oder 0 Treffer aus der Suche der verlinkten Workspaces.
• Fix: Prüfe GET /api/health/rag; kontrolliere WidgetWorkspace für das Widget (GET /api/widgets/:id/workspaces); bestätige Collector up (GET :3210/api/health).

LanceDB table missing / Query-Fehler

• Ursache: Per-Workspace-Tabelle ws_<name>_<shortId> nicht erstellt oder Storage verschoben.
• Fix: Prüfe, dass der STORAGE_PATH des Collectors unverändert ist; reindexiere Wiki/Dokumente.

Agent & LLM

Agent-Abbruch: unknown_tool_breaker

• Ursache: Circuit Breaker BOT-03 - 3 unbekannte Skills in Folge / 5 insgesamt. Oft ein Modell, das nicht registrierte Tools halluziniert.
• Fix: Nutze ein fähigeres Modell oder reduziere die aktivierten Skills; prüfe die MCP-Verbindung enabled und die registrierten Skills (mcp_<conn>_<tool>).

Agent-Abbruch: wallclock / token_budget / context_overflow

• Fix: Erhöhe die Envs AGENT_WALLCLOCK_TIMEOUT_MS (Standard 600000), AGENT_MAX_TOTAL_TOKENS (200000), AGENT_MAX_CONTEXT_BYTES (500000). Für einfache Tasks senke sie, um Stalls zu vermeiden. Siehe 03 - Configuration § Agent watchdog.

Modell antwortet nicht / Timeout lokales LLM

• Ursache: Ollama down oder Modell nicht gepullt; LLM_TIMEOUT=0 = kein Timeout (langsame lokale LLMs).
• Fix: ollama list / ollama pull gemma4:latest; prüfe OLLAMA_BASE_URL (http://ollama:11434 im Compose). Provider-Fallback: prüfe Provider.isAvailable (Polling 30s).

Provider-Fallback nicht ausgelöst

• Ursache: Kein alternativer Provider verfügbar (isAvailable=false) oder globaler Default nicht gesetzt.
• Fix: Provider hinzufügen (POST /api/providers), Default setzen (PUT /:id/set-default), deriveCapabilities-Tag prüfen. Frontend-Fallback 3-Tier mit Undo-Toast.

Widget

Widget lädt nicht / iframe leer

• Ursache: allowedOrigins enthält die Host-Origin nicht → dynamisches CORS fail-closed.
• Fix: Origin zu Widget.allowedOrigins hinzufügen (CSV-String, max 2000 Zeichen). Prüfe, dass GET /api/config/:widgetId antwortet.

Lead Capture 403

• Ursache: config.leadCaptureEnabled=false für dieses Widget.
• Fix: Im Widget-Modell aktivieren (Admin UI oder API).

Rate Limit 429 am Widget

• Ursache: Limiter-Kette - widgetDailyMessageLimiter (5/24h per Widget+IP, Override sessionLimitPerDay), widgetChatLimiter (30/min per widgetId, Override rateLimitPerMinute), widgetSessionLimiter (50 Session-Erstellungen/Tag per IP), widgetLeadLimiter (3/h per IP).
• Fix: Per-Widget-Overrides erwägen (rateLimitPerMinute/sessionLimitPerDay); prüfe, welcher Limiter getriggert hat (Header Retry-After / Body error).

MCP

Marketplace-Installation 201, aber Tools nicht verfügbar

• Ursache: connectMCPServer ist fire-and-forget; der Fehler wird geloggt, aber nicht propagiert.
• Fix: POST /api/mcp-connections/:id/test (10s, gibt {success, toolCount, error} zurück). Prüfe den Transport-Fallback D-09; kontrolliere activeConnections via GET /api/mcp-connections/statuses.

MCP automatisch deaktiviert

• Ursache: Webhook-style Auto-Disable? Nein - die MCP-Verbindung bleibt enabled; der Webhook deaktiviert sich nach 10 aufeinanderfolgenden Fehlern selbst. Für MCP setzt der 30-min Health Check healthStatus (stale/down), deaktiviert aber nicht die Verbindung.
• Fix: Für den Webhook manuell reaktivieren; für MCP ist das Health-Badge informativ.

MCP-Tool in einem Chat nicht verwendet

• Ursache: Aktive Per-Chat-Pins, die die Verbindung ausschließen, oder Verbindung disabled.
• Fix: GET /api/chats/:chatId/pins; prüfe resolveSkillsForChat (kein Pin → alle enabled Verbindungen des Workspace).

Lizenz

402 Payment Required bei einer Feature

• Ursache: requireFeature(flag) oder requireFeatureLimit hat gegatet (Community).
• Fix: LICENSE_KEY Enterprise setzen, oder auf Community mit Limits bleiben. Der Error-Body enthält feature, tier, limit?, current?.

Enterprise zur Runtime abgelaufen

• Verhalten: Graceful Degradation zu Community (kein Restart); Warn in den Logs.
• Fix: LICENSE_KEY erneuern; getLicenseInfo() liest zur Runtime neu.

Sicherheit & Audit

Audit Log schreibt nicht

• Ursache: Das Audit Log ist ein Enterprise-Modul - in Community ist logEvent ein No-op (der Write-Delegate ist nicht registriert), also wird kein Event aufgezeichnet.
• Fix: Enterprise für Audit Log + Immutabilität (audit_log_immutable). Prüfe den korrekten entityType in den Filtern (GET /api/event-logs). Event-Webhooks laufen in Community trotzdem (fire-and-forget).

DLP redigiert keine PII

• Ursache: DLP_ENABLED=false via Settings (der Standard in v0.22 ist "true" - jemand hat es deaktiviert), oder eine Rolle in DLP_BYPASS_ROLES, die vom Scan befreit.
• Fix: DLP_ENABLED=true via Settings prüfen/setzen. Redaction über 10 Built-in database-backed Patterns: die 6 Originale (email, credit_card, ssn, api_key, aws_key, private_key) plus die 4 EU/IT (it_vat_iva, it_codice_fiscale, iban, eu_phone - letzteres als DISABLED geseedet für Admin-Review); Custom-Patterns bis 50 über das DLP Patterns-Panel. SSE done → dlp_matches (das Frontend zeigt die DLPNotice unter der Nachricht).

Backup

Backup-Job bleibt ewig "running"

• Ursache: Worker tot ohne Cleanup; DB-Mutex BackupLog.status="running".
• Fix: cleanStaleLocks markiert running >2h beim nächsten Bootstrap als failed. Starte den Server neu, um es zu triggern, oder aktualisiere den Status manuell.

Checksum-Mismatch beim Restore

• Ursache: Korruptes Archiv / partieller Upload.
• Fix: SHA-256 Streaming wird beim Upload berechnet; prüfe die Zieldatei. Stelle aus dem nächsten Log wieder her.

Bekannte Dokumentations-Diskrepanzen

Schneller Health Check

curl localhost:3000/api/health        # { database, collector, disk }
curl localhost:3000/api/health/rag    # RAG-Status
curl localhost:3210/api/health        # collector
curl localhost:3211/health            # widget

Cross-Link

• Config/Env: 03 - Configuration
• Internals: 05 - Feature Guide
• Deploy: 09 - Deployment