Troubleshooting

The theme doesn't show up in Keycloak

Check where the JAR landed (/opt/keycloak/providers/ in the examples here) and confirm the archive actually contains META-INF/keycloak-themes.json and theme/<theme-id>/login/theme.properties. Select the theme by its internal ID, not the JAR's filename. On an optimized build, rebuild the image after swapping the JAR.

For a folder export, check themes/<theme-id>/login/theme.properties: an extra nested directory is the usual culprit. See deployment.

It looks right in the editor, but not on the real login page

First confirm which realm and client your app is actually using, and which theme is assigned there: it's easy to check the wrong one. Then check the server version, the deployed artifact, and your browser's network tab for CSS, fonts, or images that 404.

Developing against a folder mount? Make sure you've disabled theme caching, see deployment. Running more than one server instance? Confirm they're all on the same image before assuming it's a CSS bug.

A language shows in the preview but not on the real server

Enable internationalization on the target realm and select the same languages there: exporting message bundles doesn't do this for you. Then test a fresh login and make sure you actually deployed the latest export.

A custom page vanished from the preview

Check the CLI's terminal output: it names the missing FreeMarker expression and file. Either add the sample data it needs in kc-page.ts, or guard the value in your template if it's genuinely optional at runtime too. A macro-only helper file, with no standalone page, legitimately renders nothing on its own.

Also worth checking: does the real server actually provide the value your template expects? A mock only makes the preview render: it doesn't add anything to Keycloak itself.

Hand-edited CSS isn't loading

Check that theme.properties lists your stylesheet under styles, that the path is relative to login/resources, and that the preview is actually pointed at your local theme. On Bootstrap or Carbon, also check the framework-specific custom CSS file.

"Save to project" is missing

That's a local-CLI feature. The hosted editor only exports JARs, and in supported browsers, folders. Start the CLI and use its local URL if you want to write straight into your project.

A weekly Keycloak update failed

If you maintain this project: check the first failed workflow step. It's usually either a new CSS hook that needs an adaptation-rule update, or an upstream template change that broke a stored patch: re-running the same rules won't fix either. Follow the update runbook.

If you just consume a released theme: nothing to do. Keep your deployed artifact as-is and test the Keycloak upgrade in staging first: the updater never touches themes you've already exported.