Diagnosing Liquibase Checksum Validation Failures: MD5 vs SHA‑256 Mismatches

Problem you’ll see

During a deployment Liquibase stops with a message such as:

Validation Failed:
  1 change sets check sum
     db/changelog/v1.2.xml::JIRA-123-create-users-table::alice was: 8f3c2a1e (expected) but is: 3b9d7f4a (computed)

The run blocks until the stored checksum in DATABASECHANGELOG matches the checksum Liquibase computes from the current changelog file.

Cause / diagnostic matrix

Observed symptom	Likely root cause	Quick test
Expected vs computed checksum differ, but the SQL logic looks unchanged	File encoding or line‑ending change (CRLF ↔ LF)	file -i db/changelog/v1.2.xml shows charset=us-ascii vs charset=utf-8 or dos2unix reports conversions
Checksum column in DB is NULL or a value you edited manually	DBA manually updated DATABASECHANGELOG.md5sum	Query SELECT id,author,filename,md5sum FROM DATABASECHANGELOG WHERE id='JIRA-123-create-users-table';
Error mentions “algorithm changed from MD5 to SHA‑256”	Liquibase upgraded from pre‑4.0 (MD5) to 4.x (SHA‑256)	liquibase --version shows 4.20+ and no liquibase.checksum.algorithm property set
Duplicate id/author/filepath rows appear in history	Copy‑paste or bad merge created duplicate changeset entries	liquibase history --verbose | grep -c "JIRA-123-create-users-table" returns >1
Checksum differs after you edited the changelog (added a column, changed a type)	Intentional content change after the changeset already ran	git diff db/changelog/v1.2.xml shows real SQL differences

Ordered verification steps

1. Capture full error – run the failing command with --log-level=DEBUG to see the exact expected/computed values.

   liquibase update --log-level=DEBUG

2. List deployed changesets and stored checksums – requires a DB user with SELECT on DATABASECHANGELOG.

   liquibase history --verbose

3. Compare file content to stored checksum – compute the same algorithm Liquibase uses.

   # For MD5 (pre‑4.0)
   md5sum db/changelog/v1.2.xml
   # For SHA‑256 (4.0+)
   sha256sum db/changelog/v1.2.xml

4. Verify file encoding / line endings.

   file -i db/changelog/v1.2.xml
   # Normalise if needed
   dos2unix db/changelog/v1.2.xml
   # Or via Git
   git add --renormalize .

5. Check for duplicate changeset identifiers.

   SELECT id,author,filename,COUNT(*)
   FROM DATABASECHANGELOG
   GROUP BY id,author,filename
   HAVING COUNT(*) > 1;

6. Confirm Liquibase version and checksum algorithm setting.

   liquibase --version
   # Show effective property
   grep -i checksum.algorithm liquibase.properties

Targeted remediation per finding

1. Intentional content change

Run liquibase clear-checksums (requires UPDATE on DATABASECHANGELOG) then redeploy.

liquibase clear-checksums
liquibase update

Risk: rewrites checksums for *all* changesets; run first in a non‑prod environment and verify with liquibase validate.

2. Encoding / line‑ending drift

Normalize line endings, then clear checksums once.

dos2unix db/changelog/*.xml
# or enforce via .gitattributes
echo "*.xml eol=lf" >> .gitattributes
git add --renormalize .
git commit -m "Normalize line endings for changelogs"
liquibase clear-checksums
liquibase update

3. Manual DATABASECHANGELOG edit

Either update the row to the correct computed checksum or run clear-checksums.

# Example: set to SHA‑256 value you computed
UPDATE DATABASECHANGELOG
SET md5sum = '3b9d7f4a...'
WHERE id = 'JIRA-123-create-users-table'
  AND author = 'alice'
  AND filename = 'db/changelog/v1.2.xml';
# Then validate
liquibase validate

Document any manual DB edit in version control.

4. Liquibase version upgrade (MD5 → SHA‑256)

Two options:

• Compatibility mode – add liquibase.checksum.algorithm=MD5 to liquibase.properties (deprecated on 4.20+).
• Migrate to SHA‑256 – run clear-checksums once, then keep the default SHA‑256.

# Option A (temporary)
echo "liquibase.checksum.algorithm=MD5" >> liquibase.properties
# Option B (recommended)
liquibase clear-checksums
liquibase update

5. Duplicate changeset entries

Remove the duplicate from the changelog file, then sync the log so the remaining entry is marked ran.

# Edit changelog to keep a single 
liquibase changelog-sync
liquibase validate

Escalation criteria

Engage a DBA or architecture review when any of the following occur:

• Mismatch persists after clear-checksums *and* you have verified file integrity (hash matches, no encoding issues).
• DATABASECHANGELOG shows gaps or out‑of‑order dateexecuted values across environments.
• Multiple environments (dev, staging, prod) diverge while using the same changelog source.
• Rollback fails because the rollback SQL checksum does not match the stored value.
• Security policy forbids clear-checksums without an audit trail.

Verification after fix

1. liquibase validate – should exit with zero errors.
2. liquibase status --verbose – every changeset shows Ran with a checksum that matches sha256sum (or md5sum) of the current file.
3. Deploy to staging with --dry-run and inspect generated SQL for unexpected statements.
4. Spot‑check: SELECT md5sum FROM DATABASECHANGELOG WHERE id='JIRA-123-create-users-table'; compare to sha256sum db/changelog/v1.2.xml.
5. Add CI gate: liquibase validate + liquibase future-rollback-sql must pass before merge.

Limitations & practical notes

• clear-checksums rewrites *all* stored checksums; use only after confirming the changelog is the authoritative source and test in a non‑prod DB first.
• Setting liquibase.checksum.algorithm=MD5 on Liquibase 4.20+ is deprecated; plan a migration to SHA‑256.
• Git autocrlf=input on Windows can silently flip line endings; enforce *.xml eol=lf in .gitattributes for all changelog files.
• Manual edits to DATABASECHANGELOG bypass Liquibase’s audit trail; any such change must be version‑controlled and documented.
• Duplicate detection relies on a unique combination of id, author, and filepath; adopt semantic IDs (e.g., JIRA-123-create-users-table) to avoid collisions.

Quick reference cheat‑sheet

# 1. Diagnose
liquibase update --log-level=DEBUG
liquibase history --verbose

# 2. Compute local checksum
sha256sum db/changelog/v1.2.xml   # or md5sum for old versions

# 3. Fix line endings
dos2unix db/changelog/*.xml
# or git add --renormalize .

# 4. Clear checksums (non‑prod first!)
liquibase clear-checksums

# 5. Validate & deploy
liquibase validate
liquibase update

# 6. CI gate (add to pipeline)
liquibase validate && liquibase future-rollback-sql