Troubleshooting

Quick fixes for issues seen in production and local development. For the full list, see the repository README.

PostgreSQL: password authentication failed for user "jigsaw"

The data directory was initialized with a different password than POSTGRES_PASSWORD in .env. On a disposable dev machine you can reset:

docker compose down
sudo rm -rf data/postgres
sudo ./install.sh

Traefik: Docker API version too old

Update the repo and recreate containers:

git pull && docker compose down && docker compose up -d

SSL certificate timeout during install

• Confirm A records for panel, auth., and traefik. hostnames
• Ensure ports 80 and 443 are reachable from the internet
• Inspect docker compose logs traefik for ACME errors or rate limits

Keycloak slow or "Authentication is temporarily unavailable"

First boot can take 30–60 seconds. Check logs:

docker compose logs -f keycloak jigsaw

Invalid parameter: redirect_uri

In Keycloak, the jigsaw-panel client must allow https://<PANEL_DOMAIN>/auth/callback. The installer usually sets this; after domain changes, update the client and restart the panel:

docker compose restart jigsaw

ERR_TOO_MANY_REDIRECTS

Clear cookies for the panel and auth hostnames; use the exact configured hostname (not an IP alias).

OIDC issuer mismatch

Pull latest config and recreate the panel container:

git pull && docker compose up -d --force-recreate jigsaw

Local dev: Keycloak not ready

curl -sf http://localhost:8080/realms/jigsaw/.well-known/openid-configuration | head -c 120

← Home