Troubleshooting

Symptom	First checks
UI cannot reach API	Confirm API port 5202, `NEXT_PUBLIC_API_BASE_URL`, and nginx `/api` proxy configuration.
Stack is running but not ready	Check backend health/readiness and database provider/connection settings; inspect sanitized logs.
AI unavailable	Check `AI_SERVICE_BASE_URL`, matching `AI_SERVICE_TOKEN`, sidecar health, model/provider settings, and policy gates.
Mail/reset unavailable	Check SMTP enablement, host/port/TLS, credentials, sender, and provider limits.
Migration failure	Preserve the database and logs; do not delete/recreate it. Use a disposable reproduction and the migration guide.
Browser test failure	Confirm the harness owns its ports and isolated database; do not point it at dev/production data.

For deployment or restore incidents use infrastructure and the root BLOCKERS.md.