How to resolve checksum errors

Applies to: 

• Liquibase Pro
• Liquibase Open Source (Community)

Conditions:

• All versions of Liquibase Pro or Open Source

Issue Summary:

When doing a deployment through Liquibase, all changes are stored in the DATABASECHANGELOG table. One value stored is the checksum, which is an MD5 sum of the changeset.

During deployment, each changeset in the changelog will have its checksum calculated. If the changeset has already been deployed, the calculated checksum value will be compared against what is in the DATABASECHANGELOG table for that changeset. 

If the calculated checksum differs from what is stored in the DATABASECHANGELOG table and doesn't have an attribute (runOnChange or runAlways) to update the checksum, a checksum error will occur.

Error Message:

Unexpected error running Liquibase: Validation Failed:
     X changesets check sum
          Y was: 8:9c34242a492c0090b3ee3301b2439c81 but is now: 8:54e300693f0fe1d549c06d6f01e9a62b

X: number of changesets that have different checksums.

Y: name of the file that has a different checksum.

The error message will also show what the previous deployment checksum was and what is calculated for the current deployment. 

Potential Root Causes:

The following conditions can cause a checksum error:

1. The file's content has been modified.
   1. This can range from the query being changed or comments being added to the file. When using certain XML tags, such as includeAll, include, or SQLFile, the entire content of the file will be used in the checksum calculation, so if the file has any modifications, this will cause a checksum error.
2. The file path has changed. 
   1. Using the relative file path attribute in the XML changelog is recommended. 
3. The file's encoding has/is being changed.
   
   1. If the encoding switch causes characters to break in the file, such as � appearing, this will cause the checksum to be different.

Troubleshooting:

Should the file be deployed again?

There are two scenarios involved in checksum errors

1. The changeset should be deployed
   1. The changeset needs to be labeled for the checksum to be recalculated on deployment. Either adding runOnChange or runAlways will resolve this issue.
2. The changeset should not be deployed.
   1. Something is causing Liquibase to calculate a different checksum for a changeset already deployed, which could either be that the file was modified or the pipeline modified the file's content/encoding.

Verify the difference

One of the first steps in verifying the checksum difference is manually checking the calculated checksum for the changeset causing the error.

1. Run the calculate-checksum command against the changeset with the checksum error.
2. Query the DATABASECHANGELOG table for the file with the checksum error. 
3. Compare the two checksums in steps 1 and 2 to verify they are different.

Check for file modifications

The next step is to isolate the file with the changeset in question and check if it has been modified since the original deployment.

1. Navigate in your SCM (Source Control Management) to where the file is located and review the commit history.
2. Compare the commit history to the deployment date in the DATABASECHANGELOG table.
3. If the commit history is more recent than the deployment date, the file has most likely been modified since the original deployment date, which would cause a checksum error.

Check for encoding changes

Some of the encodings of a file will cause the underlying content of the file to change (i.e., characters will change). If there is any change to the characters, broken characters appearing (�), or Unicode characters switching, such as À to A, this will cause the checksum to differ.

1. Go over the changeset/file and ensure everything is correctly formatted. 

How to resolve:

Above is a list of potential root causes that could impact the checksum. 

• Should the file be deployed again

• Check for file modifications

• Check for encoding changes

If an above section has identified a root cause issue that has been resolved, the checksum error should no longer appear during deployment. If there is still a checksum error, the checksum can be manually updated for the changeset causing the error. In the section 'Verify the difference', copy the new checksum value, and update the changeset's checksum value in the DATABASECHANGELOG table.