Diagnosing Liquibase Validation Failures in JHipster Applications

Recognizable condition

The application fails to start during boot and the console or log file shows a Liquibase exception such as:

• "Validation Failed: checksum mismatch"
• "Unexpected changeSet count"
• "Validation error: missing changelog file"

These messages indicate that Liquibase cannot reconcile the current state of the DATABASECHANGELOG table with the expectations defined in the changelog files.

Cause / diagnostic table

Symptom	Likely cause
Checksum mismatch	Existing changelog file was edited after it was already applied (e.g., changing SQL, formatting, or whitespace).
Unexpected changeSet count	ChangeSets were added or removed manually, or a baseline was created against a schema that diverges from the changelog.
Missing changelog file	The master changelog references a file that was deleted or renamed.
Validation error on SQL	Manual DDL was executed directly on the database outside of Liquibase, causing drift.

Ordered checks

1. Examine the startup stack trace – locate the line that mentions liquibase.exception.ValidationFailedException or liquibase.changelog.ChangeSet. This confirms the failure originates from Liquibase validation.
2. Run the validation goal – from the project root execute:

   # Maven
   ./mvnw liquibase:validate
   # Gradle
   ./gradlew liquibaseValidate
   

   Run with the same profile used at startup (e.g., -Pprod) and ensure you have read access to the configured datasource.

3. Inspect the master changelog – open src/main/resources/config/liquibase/master.xml (or the equivalent) and look for recent additions, deletions, or modifications to <include> elements.
4. Compare checksums – query the DATABASECHANGELOG table:

   SELECT id, author, filename, checksum FROM DATABASECHANGELOG ORDER BY dateexecuted;

   Then compare each checksum value with the one computed by Liquibase for the corresponding changeSet (visible in the validation output). Mismatches point to edited files.

Fixes tied to findings

• Checksum mismatch – if the stack trace or validation output shows "checksum mismatch" for a specific changeSet:
  1. Backup the database (pg_dump, mysqldump, etc.) before proceeding.
  2. Clear the stored checksums:

     ./mvnw liquibase:clearChecksums -Dliquibase.url=jdbc:postgresql://host:port/db -Dliquibase.username=user -Dliquibase.password=pass

     Replace placeholders with your actual connection details.

  3. Re‑run validation to confirm success, then restart the application.
• Edited or missing changeSet – if a changeSet was altered or removed:
  1. Revert the file to its version in source control (e.g., git checkout HEAD -- src/main/resources/config/liquibase/changelog/20230101_add_table.xml).
  2. If the change was intentional and must be kept, create a new changeSet that captures the desired state instead of editing the existing one.
  3. After fixing, run liquibase:validate again.
• Manual SQL drift – if DDL was applied directly:
  1. Capture the manual statement as a new changeSet (using liquibase:generateChangeLog or hand‑crafted XML/SQL).
  2. Add the new changeSet to the master changelog.
  3. Run validation and start the app.

Escalation criteria

If validation still fails after:

• Running liquibase:clearChecksums,
• Reconciling all changeSets (reverts or new changeSets), and
• Ensuring no manual DDL remains untracked,

consider the following steps:

1. Generate a baseline changelog that reflects the current database state:

   ./mvnw liquibase:diffChangeLog -Dliquibase.referenceUrl=jdbc:postgresql://host:port/db -Dliquibase.changeLogFile=src/main/resources/config/liquibase/changelog/baseline_$(date +%Y%m%d).xml

2. Review the generated file, remove any objects that should be managed by Liquibase, and add the baseline as the first entry in master.xml.
3. Alternatively, migrate to a clean database instance (e.g., a fresh schema) and let Liquibase create the schema from scratch.
4. Involve the database administrator to verify that the target schema is compatible with the application’s expectations.

Example scenario

A developer edited 20221101_create_user_table.xml to add a column directly in the XML after the changeSet had already been applied to production. On the next deploy, the logs show:

liquibase.exception.ValidationFailedException: Validation Failed: checksum mismatch for changeSet src/main/resources/config/liquibase/changelog/20221101_create_user_table.xml::20221101-create-user-table::jhipster

Following the ordered checks:

1. The stack trace points to the validation step.
2. ./mvnw liquibase:validate reports the same checksum mismatch.
3. The master changelog shows the file is still included.
4. A query of DATABASECHANGELOG reveals the stored checksum does not match the newly computed one.

The fix is to run liquibase:clearChecksums (after backing up the DB) and then restart the application. Validation now passes and the app starts.

Verification

After applying any fix:

1. Start the application and confirm that no Liquibase exceptions appear in the startup log.
2. Re‑run liquibase:validate and ensure it reports "Validation Successful".
3. Check the DATABASECHANGELOG table: checksums should now match the values shown in the validation output, or new entries should be present for added changeSets.

Limitations

• Clearing checksums does not protect against future manual edits; it only resets the stored values.
• If the database schema has drifted significantly, a simple checksum reset may mask deeper incompatibilities.
• The procedure assumes you have access to the database credentials used by the application; without them you cannot run the Liquibase goals.

Diagram

Labels: Startup → Liquibase Validate → Checksum Comparison