How to fix Liquibase: Checksum validation failed in PostgreSQL

PostgreSQLINTERMEDIATEMEDIUMUpdated Dec 29, 2025· 217 views

Liquibase checksum validation fails when a previously executed changeset has been modified since it was first applied to the database. The stored checksum no longer matches the calculated checksum of the current changeset, triggering a validation error. Resolve this by accepting the new checksum, using validCheckSum tags, or clearing outdated checksums.

Quick fix

Fixes Liquibase: Checksum validation failed

Checksum validation failed: changeset-id
Expected: 1:abc123def456
Actual: 1:xyz789uvw012
  1. Identify the problematic changeset
  2. Determine if the modification is intentional
  3. Option A: Use validCheckSum tag (Recommended for one-time fixes)
  4. Option B: Add runOnChange attribute (For intentional modifications)
postgresql — error
Checksum validation failed: changeset-id
Expected: 1:abc123def456
Actual: 1:xyz789uvw012
Liquibase: Checksum validation failed

What this error means

Liquibase tracks all applied changesets by storing their MD5 checksums in the DATABASECHANGELOG table. When Liquibase runs, it recalculates the checksum of each changeset and compares it to the stored value. If a changeset has been modified after being applied to the database, the checksums will not match, and Liquibase raises a validation error to prevent accidental re-execution of altered changes. This error acts as a safety mechanism because modifying applied changesets can corrupt database state or break assumptions made during the original migration. The error forces developers to explicitly acknowledge and handle the checksum discrepancy before proceeding.

Typical symptoms

  • Liquibase deployment fails with "Checksum validation failed" message
  • Error appears during liquibase update or validate commands
  • Migration process halts and prevents database updates
  • Error message includes both expected (old) and actual (new) checksums
  • Problem persists across different environment deployments

Common causes

  1. The changeset SQL or XML content has been modified after being applied to the database (most common)
  2. File encoding changed (e.g., from UTF-8 to ASCII), causing different checksum calculation
  3. Liquibase version upgraded, resulting in different checksum algorithms for the same content
  4. File path changed when using relative paths in changelog includes
  5. Line ending changes (CRLF vs LF) altered the file content hash
  6. Whitespace or formatting changes in the changeset content

How to fix "Liquibase: Checksum validation failed"

1Identify the problematic changeset

Check the Liquibase error message to identify which changeset has the checksum mismatch. The error output will show:

bash
Checksum validation failed: changeset-id
Expected: 1:abc123def456
Actual: 1:xyz789uvw012

Note both the changeset ID and the two different checksum values.

2Determine if the modification is intentional

Check your version control system to see if the changeset was intentionally modified:

bash
git log -p path/to/changelog.xml | grep -A 10 -B 10 "changeset-id"

If the modification is intentional and safe (like fixing a bug), proceed with accepting the new checksum. If it was accidental, revert the change.

3Option A: Use validCheckSum tag (Recommended for one-time fixes)

Add a <validCheckSum> tag to accept the old checksum as valid. This tells Liquibase that both the old and new checksums are acceptable:

xml
<changeSet id="my-changeset" author="dev">
  <validCheckSum>1:abc123def456</validCheckSum>
  <!-- your SQL here -->
</changeSet>

Alternatively, use the special value "1:any" to accept any checksum (use with caution):

xml
<validCheckSum>1:any</validCheckSum>

This is useful when you've already applied the changeset to production and need to accommodate the checksum difference on other environments.

4Option B: Add runOnChange attribute (For intentional modifications)

If the changeset should be re-executed with the new content, add the runOnChange="true" attribute:

xml
<changeSet id="my-changeset" author="dev" runOnChange="true">
  <!-- your modified SQL here -->
</changeSet>

This tells Liquibase to recalculate the checksum on every deployment and re-run the changeset if content changed. Use this when the modification is intentional and should be applied to all environments.

5Option C: Clear and recalculate checksums (For version upgrades)

If the issue occurred after upgrading Liquibase versions, clear the old checksums and let Liquibase recalculate them:

bash
# Using the old Liquibase version first (recommended)
liquibase clear-checksums

# Then upgrade and run normally
liquibase update

This is the safest approach when Liquibase algorithm improvements change checksum calculation. Always use the OLD version to clear before upgrading.

6Option D: Manually update DATABASECHANGELOG table (Last resort)

If other options aren't viable, you can manually update the stored checksum in the database:

sql
UPDATE databasechangelog
SET md5sum = '1:xyz789uvw012'
WHERE id = 'my-changeset' AND author = 'dev';

Use the NEW checksum value from the error message. Only do this if you're confident the modification is safe and consistent across all environments.

Advanced notes

Best Practices for Avoiding Checksum Errors: (1) Never modify an applied changeset once it's been deployed. Instead, create a new changeset with the fix. (2) If you must modify an unapplied changeset (only in development), use the validCheckSum tag before committing. (3) When upgrading Liquibase, always run clear-checksums with the old version first. (4) Use consistent file encoding (UTF-8) and line endings (LF) across your team. (5) Prefer using relative file paths in includes to avoid path-related checksum issues. Version-Specific Issues: Liquibase 4.21.x and 4.23.x have known issues where checksum calculation changed for certain changeset types (dbms-specific changes, sequence creation). If upgrading within these versions, clear-checksums is essential. PostgreSQL-Specific: Ensure your database user has appropriate permissions to query the databasechangelog table when Liquibase validates checksums. Connection pooling tools may also interfere with transaction handling during validation.

Frequently asked questions

What does "Liquibase: Checksum validation failed" mean?
Liquibase tracks all applied changesets by storing their MD5 checksums in the DATABASECHANGELOG table. When Liquibase runs, it recalculates the checksum of each changeset and compares it to the stored value. If a changeset has been modified after being applied to the database, the checksums will not match, and Liquibase raises a validation error to prevent accidental re-execution of altered changes.
How do I fix "Liquibase: Checksum validation failed"?
Liquibase checksum validation fails when a previously executed changeset has been modified since it was first applied to the database. The stored checksum no longer matches the calculated checksum of the current changeset, triggering a validation error. Resolve this by accepting the new checksum, using validCheckSum tags, or clearing outdated checksums.
What causes "Liquibase: Checksum validation failed"?
The changeset SQL or XML content has been modified after being applied to the database (most common) File encoding changed (e.g., from UTF-8 to ASCII), causing different checksum calculation Liquibase version upgraded, resulting in different checksum algorithms for the same content
Is the "Liquibase: Checksum validation failed" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading