# 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](../infrastructure/README.md) and the root [BLOCKERS.md](../../BLOCKERS.md).