Troubleshooting¶
Common local-development problems and their fixes. For deployed environments, see the Runbook.
Ports already in use¶
make up and the dev servers claim these host ports:
| Port | What |
|---|---|
| 8080 | api-gateway |
| 8090 | Keycloak |
| 5432 | Postgres |
| 3000 | Grafana |
| 9090 | Prometheus |
| 5173 | web app dev server (make web) |
| 5174 | brand dashboard dev server (make brand) |
| 8000 | docs dev server (make docs) |
If a container fails to start with a bind error, find the squatter with
'lsof -i :
make up never becomes healthy¶
make health shows which container is stuck; make logs (or
'docker compose logs
- Keycloak is slow on first boot (realm import): give it a minute before digging.
- A service restarts in a loop with a database error: check for a migration failure in its logs. If the local data is disposable, make up-build rebuilds from scratch and wipes the local database.
- /ready returns 503: inspect the response's named checks and the service logs. Go stateful services probe Postgres and Kafka; TypeScript services currently probe Postgres only; the gateway has a static readiness handler. Readiness should recover when the reported dependency does.
make check fails¶
- Contract drift: regenerate with make contracts-gen; never edit 'contracts/gen/**' by hand.
- Docs build: make docs-build treats MkDocs warnings as failures. The current link plugin reports some missing anchors and navigation omissions as informational messages, so review the full output even when the command exits successfully.
- Boundary violations: make check-boundaries and the linters enforce the layout rules; the error names the rule.
No data where data is expected¶
- Grafana panels empty: metrics appear only after traffic; drive a scan and wait one 15s scrape interval.
- Brand dashboard empty: run make seed on a running stack, wait one flush cycle, and log in as one of the demo brand owners (Quick Start). Seeding is not repeatable; re-seed only after make up-build.
- Brand QR codes resolve as "unknown product": confirm the producer simulators are healthy, then wait for Passport's configured synchronization interval. Restart Passport only if periodic synchronization does not recover; see the Runbook.