Keycloak upgrade guide: how to upgrade safely
- Database migrations run automatically. Config, themes and extensions are what break.
- Read the migration notes for every version you're skipping, not just the target.
- Rehearse on a copy of production data, with a tested rollback.
Why teams fall behind
Keycloak releases often. Each skipped version adds breaking changes, so the upgrade feels riskier and gets put off again. Meanwhile, older versions miss security fixes.
Still on WildFly?
Keycloak 17 switched to the Quarkus-based distribution, and the legacy WildFly distribution has since been removed. If you're still running it, the upgrade is also a migration: configuration moves from standalone.xml to Keycloak's own options, and custom providers must be repackaged.
What usually breaks
| Area | Watch for |
|---|---|
| Configuration | Renamed or removed options. Keycloak 25 replaced the hostname options. |
| Custom extensions (SPIs) | Changed or removed internal APIs |
| Themes | Template changes in login and account themes |
| Sessions & caching | Keycloak 26 made user sessions persistent by default, which affects database sizing |
| Client behaviour | Stricter defaults for redirects and tokens |
Upgrade checklist
- Inventory realms, clients, extensions and themes
- Read the migration notes for every version between yours and the target
- Build and test extensions against the target version's APIs
- Restore a production backup into a test environment and upgrade it
- Test logins for every app, MFA, federation and admin tasks
- Plan the cut-over window, with a database backup and tested rollback
Upgrade FAQ
Can I skip Keycloak versions when upgrading?
Database migrations handle the jump, but you still need to apply the config, theme and extension changes from every version you skip.
How often should we upgrade Keycloak?
Stay within a release or two of the latest. Small, regular upgrades are far less risky than big jumps.
Stuck on an old Keycloak? We plan upgrades and review your extensions before you start.