Troubleshooting

Sintomi comuni, causa, risoluzione. Riferimenti file:line e cross-link ai docs.

Avvio & config

Il server esce subito con process.exit(1)

• Causa: env Zod validation fallita (src/config/env.ts).
• Fix: controlla log - indica la variabile invalida. Verifica JWT_SECRET (obbl.), COLLECTOR_SECRET (obbl.), DATABASE_URL, porte. Confronta con .env.example.

COLLECTOR_SECRET mismatch tra server e collector

• Sintomo: il collector non riesce a notificare lo status documento; upload resta "processing".
• Fix: imposta lo stesso COLLECTOR_SECRET nel root .env (config singola - il layer per-package .env è stato rimosso in v0.22). Confronto constant-time → errore 401 silenzioso.

WIDGET_API_KEY mismatch widget↔server

• Sintomo: widget non carica config / chat 401 dal server.
• Fix: stessa key nel root .env (config singola). Senza key, il cache-bust push è no-op (TTL 5 min).

Config modificata da UI non ha effetto

• Causa: chiavi ALWAYS_READONLY (JWT_SECRET, DATABASE_URL, porte, URL) sono rifiutate dalla bulk settings; altre seguono DB > ENV > Default.
• Fix: per chiavi readonly, modifica .env + restart. PUT /api/system/settings ritorna { rejected: [...] } - controlla quell'array.

Database

Migrazioni in conflitto / reset dev

• Fix: in dev con DB usa-e-getta, reset con pnpm db:migrate:reset:guard (richiede PRISMA_MIGRATE_RESET_CONFIRM=yes o --force-accept-data-loss - mai in produzione). Deploy con guard: pnpm db:migrate:guard (rifiuta migrazioni destructive senza consenso esplicito). Verifica PostgreSQL 16 e DATABASE_URL corretta.

Restore backup non atomico / dati parziali

• Causa: restore usa psql --single-transaction --set ON_ERROR_STOP=on; se fallisce fa rollback completo.
• Fix: controlla log psql; safety backup pre-restore (runSafetyBackup). Usa /restore/:logId/dry-run prima del restore reale.

RAG & embedding

Vector search restituisce 0 risultati ma FTS funziona

• Causa: guard D-01 - EMBEDDING_MODEL attuale ≠ embeddingModel dei Document (es. cambiato modello dopo upload): la vector leg viene saltata e la search degrada a FTS-only.
• Fix: re-embed via POST /api/system/reembed-documents (admin, opzionale workspaceId/documentIds) per ri-embeddare i chunk col modello corrente; se serve solo ricostruire l'indice FTS dal vector DB: POST /api/system/reindex-documents. Entrambi admin-only, anche da Settings → Maintenance.

RAG degradato nel widget (status: rag-degraded)

• Causa: pre-search RAG fallita (collector down, workspace whitelist vuota) oppure 0 risultati dalla search dei workspace collegati.
• Fix: verifica GET /api/health/rag; controlla WidgetWorkspace per il widget (GET /api/widgets/:id/workspaces); conferma collector up (GET :3210/api/health).

LanceDB table missing / query error

• Causa: tabella per-workspace ws_<name>_<shortId> non creata o storage spostato.
• Fix: verifica STORAGE_PATH del collector invariato; reindex wiki/documenti.

Agent & LLM

Agent abort: unknown_tool_breaker

• Causa: circuit breaker BOT-03 - 3 skill sconosciuti consecutivi / 5 totali. Spesso modello che hallucina tool non registrati.
• Fix: usa modello più capace o riduci skill abilitate; verifica MCP connection enabled e skill registrate (mcp_<conn>_<tool>).

Agent abort: wallclock / token_budget / context_overflow

• Fix: alza env AGENT_WALLCLOCK_TIMEOUT_MS (default 600000), AGENT_MAX_TOTAL_TOKENS (200000), AGENT_MAX_CONTEXT_BYTES (500000). Per task semplici abbassa per evitare stall. Vedi 03 - Configuration § Agent watchdog.

Modello non risponde / timeout LLM locale

• Causa: Ollama down o modello non pullato; LLM_TIMEOUT=0 = nessun timeout (LLM locali lenti).
• Fix: ollama list / ollama pull gemma4:latest; verifica OLLAMA_BASE_URL (http://ollama:11434 in compose). Fallback provider: controlla Provider.isAvailable (polling 30s).

Fallback provider non triggerato

• Causa: nessun provider alternativo disponibile (isAvailable=false) o default globale non impostato.
• Fix: aggiungi provider (POST /api/providers), set default (PUT /:id/set-default), verifica deriveCapabilities tag. Frontend fallback 3-tier con toast Undo.

Widget

Widget non si carica / iframe vuoto

• Causa: allowedOrigins non include l'origine host → CORS dinamico fail-closed.
• Fix: aggiungi origine a Widget.allowedOrigins (stringa CSV, max 2000 char). Verifica GET /api/config/:widgetId risponda.

Lead capture 403

• Causa: config.leadCaptureEnabled=false per quel widget.
• Fix: abilita nel modello Widget (admin UI o API).

Rate limit 429 sul widget

• Causa: catena limiter - widgetDailyMessageLimiter (5/24h per widget+IP, override sessionLimitPerDay), widgetChatLimiter (30/min per widgetId, override rateLimitPerMinute), widgetSessionLimiter (50 creazioni sessione/giorno per IP), widgetLeadLimiter (3/h per IP).
• Fix: valuta gli override per-widget (rateLimitPerMinute/sessionLimitPerDay); controlla quale limiter ha triggerato (header Retry-After / body error).

MCP

Installazione marketplace 201 ma tool non disponibili

• Causa: connectMCPServer è fire-and-forget; fallimento logged ma non propagato.
• Fix: POST /api/mcp-connections/:id/test (10s, ritorna {success, toolCount, error}). Verifica transport fallback D-09; controlla activeConnections via GET /api/mcp-connections/statuses.

MCP disabilitato automaticamente

• Causa: webhook-style auto-disable? No - MCP connection resta enabled; è il webhook che si auto-disabilita dopo 10 fallimenti consecutivi. Per MCP, health check 30-min imposta healthStatus (stale/down) ma non disabilita la connection.
• Fix: per webhook, riabilita manualmente; per MCP, il badge health è informativo.

Tool MCP non usato in una chat

• Causa: pin per-chat attivi che escludono la connection, o connection disabled.
• Fix: GET /api/chats/:chatId/pins; verifica resolveSkillsForChat (no pin → tutti i connection enabled del workspace).

Licenza

402 Payment Required su una feature

• Causa: requireFeature(flag) o requireFeatureLimit ha gateato (Community).
• Fix: imposta LICENSE_KEY Enterprise, o resta su Community con limiti. Body error include feature, tier, limit?, current?.

Enterprise scaduto a runtime

• Comportamento: graceful degradation a Community (no restart); warn nei log.
• Fix: rinnova LICENSE_KEY; getLicenseInfo() rilegge a runtime.

Sicurezza & audit

Audit log non scrive

• Causa: l'audit log è un modulo Enterprise - in Community logEvent è un no-op (il delegato di scrittura non è registrato), quindi nessun evento viene registrato.
• Fix: Enterprise per audit log + immutabilità (audit_log_immutable). Verifica entityType corretto nei filtri (GET /api/event-logs). I webhook di evento partono comunque in Community (fire-and-forget).

DLP non redige PII

• Causa: DLP_ENABLED=false via settings (il default in v0.22 è "true" - qualcuno l'ha disattivato), o ruolo nella DLP_BYPASS_ROLES che esenta dallo scan.
• Fix: verifica/imposta DLP_ENABLED=true via settings. Redaction su 10 pattern built-in database-backed: i 6 originali (email, credit_card, ssn, api_key, aws_key, private_key) più i 4 EU/IT (it_vat_iva, it_codice_fiscale, iban, eu_phone - quest'ultimo seedato DISABLED per review admin); pattern custom fino a 50 via pannello DLP Patterns. SSE done → dlp_matches (frontend mostra la DLPNotice sotto il messaggio).

Backup

Job backup resta "running" per sempre

• Causa: worker morto senza cleanup; mutex DB BackupLog.status="running".
• Fix: cleanStaleLocks marca running >2h come failed al prossimo bootstrap. Riavvia il server per triggerarlo, o aggiorna manualmente lo status.

Checksum mismatch al restore

• Causa: archivio corrotto / upload parziale.
• Fix: SHA-256 streaming calcolato a upload; verifica file destino. Ripristina da log successivo.

Discrepanze documentali note

Health check rapid

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

Provenienza v0.28.1

Riferimento operativo - Simmetric Chat v0.28.1 (docs aggiornate 2026-10-02, census SHA `aca5b8ff`).

Cross-link

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