Troubleshooting

Common failure modes and how to resolve them.

Nothing starts at all

Every Compose service is profile-gated. If COMPOSE_PROFILES is unset or empty in tokamak-services/.env, docker compose up starts zero containers and exits without an error.

COMPOSE_PROFILES=infra,api,web,full

Service won't start

Check service health:

make tokamak-health

Common causes:

• Missing .env file — run make tokamak-setup to generate it from the template
• Port conflict — check docker ps for containers using 8080 (gateway), 5432 (Postgres), 6379 (Redis), 3001 (web), or the docs/Grafana port
• Docker not running — ensure Docker Desktop or the Docker daemon is active

Core refuses to boot

Core exits at startup if JWT_SIGNING_SECRET or KEYCLOAK_BASE_URL is set on it. Token validation belongs to the auth service; set those variables there instead.

Database errors

Re-run core's migrations:

make -C infra/docker/tokamak db-migrate

Reset the database (destroys all data):

make tokamak-down-clean
make tokamak-up-dev

Open a PostgreSQL shell to inspect state:

make -C infra/docker/tokamak db-console

Remember that core and auth own separate schemas in the same database — check both if a query comes back empty.

Authentication failures

Symptoms: 401 on every request, or 403 on endpoints the caller should be able to reach.

Check:

• The API key has not expired. tokamak auth status reports the expiry.
• SYSTEM_ADMIN_EMAIL is set if you need the first platform administrator on a fresh deployment.
• With OIDC enabled, KEYCLOAK_BASE_URL, KEYCLOAK_REALM, and KEYCLOAK_CLIENT_ID are correct and reachable from the auth container.
• For a 403, compare GET /v1/me/permissions against the permission the endpoint requires. See Access Control.

authorization unavailable or delegation token unavailable from the gateway means the gateway could not reach auth, or could not mint an internal token. Check TOKAMAK_AUTH_URL and that AUTHZ_DELEGATION_PRIVATE_KEY is set consistently across gateway replicas — if it is unset each replica generates its own ephemeral key and tokens fail verification.

Port conflicts

Check what's using a port:

lsof -i :8080
lsof -i :5432

Stop conflicting containers:

docker ps
docker stop <container-id>

Or change the port in .env and restart. Note that the docs site and Grafana both default to 3002 in some templates — set GRAFANA_PORT or DOCS_PORT if they collide.

Container logs

make tokamak-logs                              # All services
make -C infra/docker/tokamak logs-api          # gateway, core, auth
make -C infra/docker/tokamak logs-infra        # Postgres, Redis
make -C infra/docker/tokamak logs-web          # web app, docs

For a single container:

docker compose -p tokamak logs tokamak-gateway
docker compose -p tokamak logs tokamak-core
docker compose -p tokamak logs api-db

Upgrading

If you're upgrading from a previous version and seeing unexpected errors, see the Upgrading guide.

Getting help

If none of the above resolves your issue, open an issue at github.com/janhq/tokamak with the output of make tokamak-health and the relevant logs.