1.4 KiB
1.4 KiB
Troubleshooting
This is the “symptom → checks → likely fixes” page.
For deeper playbooks, see:
Triage map
| Symptom | Fast checks | Likely fix |
|---|---|---|
| UI loads but API calls fail / Activity feed blank | Browser devtools shows /api/v1/* failures; check backend /healthz |
Fix NEXT_PUBLIC_API_URL (must be browser-reachable) |
| UI redirects / Clerk errors | Is NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY set? Are Clerk redirects correct? |
Unset keys for local dev without Clerk; configure real keys for prod |
Backend /healthz fails |
Is backend container/process running? check backend logs | Fix crash loop: env vars, DB connectivity, migrations |
| Backend returns 5xx | Check DB connectivity (DATABASE_URL), DB logs |
Fix DB outage/misconfig; re-run migrations if needed |
| Browser shows CORS errors | Compare CORS_ORIGINS vs frontend origin |
Add frontend origin to CORS_ORIGINS |
Common checks
1) Verify backend health
curl -f http://localhost:8000/healthz
2) Verify frontend can reach backend
- Ensure
NEXT_PUBLIC_API_URLmatches the backend URL the browser can reach.
3) Check logs
docker compose -f compose.yml --env-file .env logs -f --tail=200 backend
Next
If you hit a recurring incident, promote it from the deep-dive page into this triage map.