2026-08-25 · run 2026-08-25-s10-missing-theme

S10: a missing theme falls back silently, and the error arrives after the window closes

Summary

The lab realm has named custom themes since the first run — seed-realm.sh's typical profile sets loginTheme: lab-login, accountTheme: lab-account, emailTheme: lab-email — and no theme files have ever been mounted. So S10 has silently been in force in every record this lab has produced.

The answer: Keycloak falls back to the built-in theme and serves a working login page. It logs the problem at ERROR level — but lazily, on the first request that needs the theme, not at startup. An operator who upgrades, watches the startup log, sees a clean start and closes the maintenance window has had no opportunity to see it.

Environment

Procedure

docker compose exec -T db psql -U keycloak -c \
  "select name, login_theme, account_theme, email_theme, admin_theme from realm"

curl -sL "http://localhost:8080/realms/lab/protocol/openid-connect/auth\
?client_id=spa-public&response_type=code&scope=openid\
&redirect_uri=https%3A%2F%2Fspa.lab.invalid%2Fcb\
&code_challenge_method=S256&code_challenge=<S256 of a verifier>"

curl -s "http://localhost:8080/realms/lab/account/"
docker compose logs keycloak | grep -i theme

Results

The login page is fully functional. Asset URLs in the served HTML resolve to resources/he5u5/login/keycloak.v2/… and resources/he5u5/account/keycloak.v3/… — the built-in themes, not the configured names.

The logging is real but late

19:03:19,962 ERROR [org.keycloak.theme.DefaultThemeManager] Failed to find ACCOUNT theme lab-account, using built-in themes
19:03:42,949 ERROR [org.keycloak.theme.DefaultThemeManager] Failed to find LOGIN  theme lab-login,   using built-in themes

Three theme-related lines in the entire container log, and all three carry the timestamp of the request that triggered them, not of startup. The ACCOUNT line appeared when the account console was first fetched; the LOGIN line 23 seconds later, when the login page was first fetched. Before those requests, the log contained nothing about themes at all.

That is the finding. The severity is right — ERROR — but the timing is wrong for an upgrade: the signal is emitted by the first user, not by the upgrade.

Outcome

• Reached ready
• Login flow renders — with the wrong branding
• Themes render — no, silently substituted
• Logged, at ERROR, but only on first use

Verification

Publishable extract

If your Keycloak upgrade loses its custom theme, Keycloak will not tell you during the upgrade. It will tell the first person who tries to log in.

We ran a realm configured with loginTheme: lab-login and no such theme mounted, on Keycloak 26.7.1 / Postgres 16.15. The login page returned HTTP 200 with a complete, working sign-in form — rendered in the built-in theme. The only signal was one line, at ERROR:

ERROR [org.keycloak.theme.DefaultThemeManager] Failed to find LOGIN theme lab-login, using built-in themes

and it was written at the moment of the first login request, not at startup. Our container log contained no theme-related line at all until somebody asked for a page.

This is a graceful fallback, and as engineering it is the right call — nobody wants an outage because a CSS file is missing. But it means the standard upgrade verification, "the server came up clean, close the window", cannot catch it. Custom themes are mounted from outside the image, so they are exactly the kind of thing an image bump, a chart change, or a moved volume quietly drops.

Add one line to your post-upgrade checks: fetch the login page and confirm the asset URLs contain your theme name, not keycloak.v2.