Description
Before reporting an issue
- I have read and understood the above terms for submitting issues, and I understand that my issue may be closed without action if I do not follow them.
Area
storage
Describe the bug
When performing a Keycloak upgrade from versions ≤ 22.0.4 directly to 26.2.x, the startup fails with a Liquibase checksum validation error:
Validation Failed: 1 changesets check sum META-INF/jpa-changelog-2.5.0.xml::2.5.0-unicode-oracle::hmlnarik@redhat.com was: 8:8b6fd445958882efe55deb26fc541a7b but is now: 8:6be40845dcc4adb4512f70ce19c71dfd
Version
26.2.0
Regression
- The issue is a regression
Expected behavior
When performing a Keycloak upgrade from versions ≤ 22.0.4 directly to 26.2.x, the startup and db migration passed without any issues.
Actual behavior
When performing a Keycloak upgrade from versions ≤ 22.0.4 directly to 26.2.x, the startup fails with a Liquibase checksum validation error:
`
Validation Failed:
1 changesets check sum
META-INF/jpa-changelog-2.5.0.xml::2.5.0-unicode-oracle::hmlnarik@redhat.com
was: 8:8b6fd445958882efe55deb26fc541a7b but is now: 8:6be40845dcc4adb4512f70ce19c71dfd
How to Reproduce?
- Start with Keycloak 22.0.4 or lower
- Run keycloak to initialize the DB (DATABASECHANGELOG will contain 8: checksums).
- Upgrade Keycloak to 26.2.0 to run db migration
- Start Keycloak, observe migration failure.
Anything else?
Cause
In versions of Keycloak up to 22.0.4, Liquibase used version 4.20.0 (and lower), which generated 8: prefixed checksums.
Starting from Keycloak 22.0.5, Liquibase was updated to 4.23.2, which defaults to 9: prefixed checksums.
In Keycloak 26.2.x, changelogs now explicitly contain only the new 9: checksums and 7:checksums.
This leads to checksum mismatch errors when upgrading from older versions directly to 26.2.x, as the existing database has 8: checksums, but the changelogs expect 9:.
Impacted upgrade paths
From Keycloak version | To Keycloak version | Result
17.x, 20.x, 21.x, 22.0.0 - 22.0.4 | 26.1.x | ✅ OK (still uses 8: checksums)
17.x, 20.x, 21.x, 22.0.0 - 22.0.4 | 26.2.0 | ❌ Fails due to checksum mismatch
22.0.5 - 26.1.x | 26.2.0 | ✅ OK (DB: 9:, changelog: 9:)
Suggested resolution
To ensure smoother upgrades, consider one of the following:
✅ Add the older checksums (8:) as valid in changelogs for compatibility.
✅ Document a required intermediate upgrade path (for example, to 22.0.5 or 26.1.x first before going to 26.2.x).