Troubleshooting

Start with the boundary that failed. A green web page is not proof that the API is ready, the worker is consuming jobs or a provider action completed.

Triage commands

docker compose ps
docker compose logs --tail=200 api
docker compose logs --tail=200 worker
curl -i http://localhost:34001/healthz
curl -i http://localhost:34001/readyz
curl -i http://localhost:8080/

healthz checks API process liveness. readyz performs a PostgreSQL query. If readyz is 503, inspect PostgreSQL health and DATABASE_URL. If the API is healthy but jobs remain pending, inspect Redis health, REDIS_URL, worker logs and the corresponding BackgroundJobRecord.

Common symptoms

Symptom	Likely boundary	Check
API starts but readiness fails	PostgreSQL	docker compose ps, database logs, credentials and migration state
Jobs do not progress	Redis or worker	Redis password/URL, worker health, queue logs, job record
ENTITLEMENT_MISSING	Organization lifecycle/limits	/api/v1/me/entitlements, activation status and platform review
Account is healthy but no live resources	Mock/live boundary	account mode, cloud.live, provider adapter implementation and sync result
Plan cannot apply	Approval, expiry or snapshot drift	run status, policy decision, approval age and current observation
Agent is offline	Heartbeat or revocation	last heartbeat, agent key status, outbound connectivity and clock
Webhook is FAILING	Destination or signature	response status, warning alert, endpoint timeout and HMAC verification
UI says unauthorized after a role change	Session cache	refresh session or revoke/re-authenticate; server remains authoritative

Do not paste credential payloads, bearer tokens, refresh tokens, API keys or unredacted provider responses into an issue. Include request IDs and timestamps instead.