Skip to content
CompanyWizard

Runbooks & troubleshooting (operations)

Admin

This page bundles common operational problems and points to the matching detail runbooks. The approach is always: symptom → first check → detail runbook.

Sign-in fails (no OTP code)

Section titled “Sign-in fails (no OTP code)”

First check: SMTP status in the System settings (last health check). Often a wrong host/port/sender, or an unreachable SMTP service in server operation. → Set up OTP sign-in

Search returns no/poor hits

Section titled “Search returns no/poor hits”

First check: the active vector backend. Without Qdrant/sqlite-vec, BM25 runs (lower hit quality). Wait for the reindex after a restore/import. → Set up Qdrant · RAG & search

PII is not pseudonymized

Section titled “PII is not pseudonymized”

First check: Presidio health. On failure no pseudonymization happens (no local fallback). → Set up Presidio

Model/MCP does not respond

Section titled “Model/MCP does not respond”

First check: API keys and provider status. After a restore/peer sync, keys must be correctly re-encrypted. → LLM API keys · MCP servers

Health probe red / container restarts

Section titled “Health probe red / container restarts”

First check: /ready and the logs. A “ready” check (e.g. database) is failing. → Monitoring & health checks

Columns missing after update / startup error

Section titled “Columns missing after update / startup error”

The cause is usually the two-spot rule (EF migration without a matching DbInitializer entry). On startup only DbInitializer.InitializeAsync runs. → Updates & version changes

Restore fails

Section titled “Restore fails”

First check: passphrase correct? App version ≥ backup version? → Backup & restore

Clients have a diverging configuration

Section titled “Clients have a diverging configuration”

First check: the diff in the Connections tab; is the host reachable? → Peer sync / server mode in operation

Diagnostic basics

Section titled “Diagnostic basics”