Troubleshooting Guide

Common problems and their fixes. Always check Monitoring Center first — it usually points straight at the failing subsystem.

Install & startup

Symptom: docker compose up exits immediately.

• Check docker compose logs app — look for missing env vars
• Ensure Postgres is reachable at DATABASE_URL
• Confirm ports 80 / 443 are free

Symptom: Readiness probe never turns green.

• pgvector or pg_cron extension not enabled → run the DB init script
• Storage bucket unreachable → verify credentials

Messaging

Symptom: Outbound messages stuck at queued.

• Confirm WhatsApp connection under Settings → WhatsApp
• Check tier and rate-limit meters in Monitoring Center
• Inspect the outbox worker logs

Symptom: No delivery/read receipts.

• Webhook subscriptions missing → re-run the WhatsApp setup wizard
• Custom domain not covered by TLS cert → certs must include the webhook subdomain

Realtime

Symptom: Typing indicator or status doesn't update live.

• Client couldn't upgrade to WebSocket — check reverse proxy (proxy_read_timeout, Upgrade header)
• Browser extension blocks WS — try incognito

Database

Symptom: permission denied for table in the app UI.

• Missing GRANT — every public-schema table needs explicit grants
• Re-run the migration and confirm grants for authenticated and service_role

Still stuck?

• Enable debug logging under Settings → Advanced
• Collect a support bundle: Support → Generate Diagnostic Bundle
• Post it on the community or your support portal