Guide 12

Troubleshooting

Diagnose and fix issues in Simmetric Chat quickly.

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 in packages/server/.env e packages/collector/.env. Confronto constant-time → errore 401 silenzioso.

`WIDGET_API_KEY` mismatch widget↔server

Sintomo: widget non carica config / chat 401 dal server.
Fix: stessa key in packages/widget/.env e packages/server/.env. 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

`pnpm db:setup` fallisce / migrazioni in conflitto

Fix: pnpm db:reset (destructive) poi pnpm db:setup. In dev con DB pulito. 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).
Fix: reindex via POST /api/system/reindex-documents (admin) o Settings → Maintenance. Tutti i chunk verranno re-embeddati col modello corrente.

RAG degradato nel widget (`status: rag-degraded`)

Causa: pre-search RAG fallita (collector down, workspace whitelist vuota).
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 (max 50). Verifica GET /api/config/:id 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: limiter per widgetId (30/min), per IP (5/day), o server hourly/daily (20/h, 5/24h per sessione).
Fix: valuta alzare limiti per Enterprise; 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: eventLogService.logEvent è async post-DB; license audit_log_immutable off (Community) → eventi loggati ma non append-only.
Fix: Enterprise per immutabilità. Verifica entityType corretto nei filtri (GET /api/event-logs).

DLP non redige PII

Causa: DLP_ENABLED=false (default).
Fix: abilita via settings (DLP_ENABLED=true). Redaction su 6 PII (email, credit_card, ssn, api_key, aws_key, private_key); SSE done → dlp_warning.

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

Doc dice	Codice dice	Fonte verità
"28 permissions"	27 (`PERMISSION_NAMES`)	codice
"12 menu sections"	13 (`MENU_SECTIONS`, +`uploads`)	codice
"7 languages" i18n	en/it/ru (file concreti)	`i18n/locales/`
`--profile enterprise` compose	non definito esplicitamente	`LICENSE_KEY` attiva Enterprise

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

Troubleshooting

Avvio & config

Il server esce subito con process.exit(1)

COLLECTOR_SECRET mismatch tra server e collector

WIDGET_API_KEY mismatch widget↔server

Config modificata da UI non ha effetto

Database

pnpm db:setup fallisce / migrazioni in conflitto

Restore backup non atomico / dati parziali

RAG & embedding

Vector search restituisce 0 risultati ma FTS funziona

RAG degradato nel widget (status: rag-degraded)

LanceDB table missing / query error

Agent & LLM

Agent abort: unknown_tool_breaker

Agent abort: wallclock / token_budget / context_overflow

Modello non risponde / timeout LLM locale

Fallback provider non triggerato

Widget

Widget non si carica / iframe vuoto

Lead capture 403

Rate limit 429 sul widget

MCP

Installazione marketplace 201 ma tool non disponibili

MCP disabilitato automaticamente

Tool MCP non usato in una chat

Licenza

402 Payment Required su una feature

Enterprise scaduto a runtime

Sicurezza & audit

Audit log non scrive

DLP non redige PII

Backup

Job backup resta "running" per sempre

Checksum mismatch al restore

Discrepanze documentali note

Health check rapid

Cross-link

Il server esce subito con `process.exit(1)`

`COLLECTOR_SECRET` mismatch tra server e collector

`WIDGET_API_KEY` mismatch widget↔server

`pnpm db:setup` fallisce / migrazioni in conflitto

RAG degradato nel widget (`status: rag-degraded`)

Agent abort: `unknown_tool_breaker`

Agent abort: `wallclock` / `token_budget` / `context_overflow`