Skip to content

Troubleshooting

General

task start fails with ".env file not found"

Run task init to create the .env file first.

Browser shows "connection refused"

Check that Docker is running and the stack is started:

docker info          # Is Docker running?
task doctor          # Full health check
task start           # Start the stack

Browser shows a certificate warning (local/dev)

This is expected with self-signed certificates. Accept the warning to proceed. If the certificate has expired:

task generate-local-self-signed-certs
task restart

Services not appearing on the dashboard

  • Verify the container is running: task status
  • Check that the container has homepage.group and homepage.name labels
  • Verify the container is on the autoproxy network
  • Restart Homepage: docker restart homepage

Port 80 or 443 already in use

Another process is using the ports Traefik needs. Common culprits:

# Find what's using the port
lsof -i :80
lsof -i :443

Stop the conflicting process or change its port before starting claritools.

Dev mode

oauth2-proxy is crash-looping

Check the logs:

docker logs oauth2-proxy --tail 20

Common causes:

"cookie_secret must be 16, 24, or 32 bytes" — The OAUTH2_PROXY_COOKIE_SECRET value in docker-compose.dev.yml is the wrong length. It must be exactly 16, 24, or 32 characters.

"failed to discover OIDC configuration" — oauth2-proxy cannot reach Keycloak. Ensure Keycloak is running and healthy:

docker logs keycloak --tail 20

Keycloak takes a few seconds to start. oauth2-proxy will retry automatically.

"middleware oauth-auth@docker does not exist" in Traefik logs

This means oauth2-proxy is not running. The ForwardAuth middleware is defined on oauth2-proxy's Docker labels, so Traefik can only register it when the container is up. Fix whatever is preventing oauth2-proxy from starting (see above).

"invalid_redirect_uri" from Keycloak

The OAuth callback URL is not in Keycloak's allowed redirect URIs. This can happen if:

  • The Keycloak realm was imported before the redirect URI list was updated
  • You are accessing a service on a host not covered by the wildcard

To fix, reset Keycloak to reimport the realm:

task stop
docker volume rm current_keycloak_data
task start

The sign-in flow, callback, and CSRF cookie must all stay on the same host. This is handled automatically by the catch-all /oauth2/ router. If you see this error:

  1. Clear your browser cookies for *.local.ciservers.net
  2. Ensure OAUTH2_PROXY_REDIRECT_URL is not set in docker-compose.dev.yml (it should be derived from the request host)
  3. Restart: task restart

Keycloak shows "hostname is not configured"

This happens when incompatible hostname options are used. The dev config uses KC_HOSTNAME (v2 hostname config). Do not use KC_HOSTNAME_URL (deprecated v1 option) alongside KC_HOSTNAME_STRICT=true.

Keycloak realm changes not taking effect

Keycloak only imports the realm on first start. If the realm already exists, changes to claritools-realm.json are ignored. Delete the volume to force reimport:

task stop
docker volume rm current_keycloak_data
task start

CD mode

Let's Encrypt certificate not issued

  • Check Traefik logs: task logs
  • Ensure DNS for *.cd.ciservers.net points to the server
  • Verify port 80 is accessible from the internet (required for HTTP challenge)
  • Check Let's Encrypt rate limits — switch to the staging resolver for testing

"Router uses a nonexistent certificate resolver"

This warning appears when the Traefik labels reference the prod certificate resolver but the current environment's Traefik config does not define it. This is harmless in local/dev mode where self-signed certs are used instead.