Schuly Docs

English

Deutsch
Français
Italiano

English

Deutsch
Français
Italiano

Appearance

Troubleshooting ​

Common failures, what causes them, and how to fix them.

The login page looks like default Keycloak (not branded) ​

The schuly theme jar isn't loaded, or the realm isn't using it.

  • Confirm the realm's loginTheme is schuly (realms/schuly-realm.json).
  • If you changed theme code, rebuild the image - the theme is baked in at build time, not loaded at runtime: docker compose -f compose.dev.yml up --build. See Theme development.

Infinite redirects, "HTTPS required", or wrong URLs in the browser ​

Keycloak doesn't know its public URL or isn't trusting the proxy headers.

  • Set KC_HOSTNAME to the full public URL (e.g. https://auth.schuly.dev).
  • Behind a TLS-terminating proxy, set KC_PROXY_HEADERS=xforwarded and KC_HTTP_ENABLED=true, and make sure the proxy forwards X-Forwarded-* headers.
  • See Self-hosting the full stack.

Realm edits to the JSON don't show up ​

The realm is imported only on the first start; afterwards an existing realm is left as-is.

  • Local dev: reset the data volume to re-import - docker compose -f compose.dev.yml down -v && docker compose -f compose.dev.yml up --build.
  • Production: the realm already exists in Postgres; apply changes in the admin console and snapshot them back with the export script (see Realm management). Don't expect the bundled JSON to overwrite a live realm.

Health check fails / can't reach /health ​

Health and metrics are on the management port 9000, not 8080.

  • Hit http://<host>:9000/health/ready from inside the network (it's intentionally not proxied to the internet).

The bootstrap admin can't log in ​

KC_BOOTSTRAP_ADMIN_USERNAME / KC_BOOTSTRAP_ADMIN_PASSWORD only create an account on the first start of a fresh database. If the database already had an admin, those variables do nothing - use the existing admin, or reset via the admin REST API.

Database connection errors on startup ​

  • Verify KC_DB_URL, KC_DB_USERNAME, KC_DB_PASSWORD and that Postgres is reachable and accepting connections (wait for its healthcheck before Keycloak starts).
  • The image is built for Postgres only - don't override KC_DB.

New users aren't prompted for 2FA / passkey questions ​

2FA enrollment behavior is defined by the browser-2fa flow and required actions - see the 2FA section in Realm management, including the migration note for pre-existing users.