Common Incidents

Backend starts but APIs fail#

Check migrations and database connectivity:

docker compose logs backend
docker compose logs postgres

For a local backend process:

cd backend
source .venv/bin/activate
alembic upgrade head

Worker is alive but workflows do not progress#

Check worker logs, Temporal UI, task queue names, and TEMPORAL_HOST / TEMPORAL_NAMESPACE.

docker compose logs worker

Also inspect matter tasks and human review tasks. A legal workflow may be waiting for attorney approval or feedback rather than failing.

Duplicate matters from retries#

This usually points to missing idempotency handling on an inbound API client or webhook consumer. Confirm whether the same external identifier was submitted more than once and whether webhook delivery or record idempotency fields captured the retry.

Documents fail to download or render#

Confirm the document row exists, the file still exists in local storage, and the path stays inside the configured storage root. For generated artifacts, confirm whether the format supports rendered preview. Visual template artifacts may be client-rendered JSON rather than server-rendered HTML.

Connector authentication failures#

Expired refresh tokens, missing provider env vars, unregistered Nango provider config, or rotated bot/webhook secrets are common causes. Confirm whether the failure affects Gmail, Telegram, Nango, SMTP/IMAP, webhook delivery, or an external tool.

Redis is unavailable#

Redis is an optimization and coordination layer, not the source of truth. Expect degraded latency or cache misses. Check REDIS_URL, Redis container health, and backend logs for circuit-breaker or fallback behavior.