JHipster Liquibase startup failures: diagnose checksum mismatches, locks and missing changelogs

Recognizable condition

A JHipster-generated Spring Boot monolith or microservice fails to start. The application context does not load, the health check stays DOWN in JHipster Registry or Kubernetes, and the logs show a Liquibase error during bootstrap.

Typical log signatures are:

• Validation Failed: checksum mismatch for a changelog
• ChangeLog lock held by another instance
• Missing changelog file or resource not found

The service is unusable until Liquibase validation passes. The problem is usually environment-specific and appears after a code merge, a redeploy, or a crash during migration.

Cause to symptom table

Ordered checks

1. Read the exact Liquibase error

Run logs for the failing instance. In Kubernetes:

kubectl logs <pod-name> -c app | grep -i liquibase

Look for the changelog name, changeSet id, and the error type. The log tells you which file and which table to inspect next.

2. Inspect DATABASECHANGELOG and DATABASECHANGELOGLOCK

Connect to the database with read permission. Use your DB client with credentials from the environment.

-- PostgreSQL example
SELECT ID, AUTHOR, FILENAME, DATEEXECUTED, MD5SUM
FROM DATABASECHANGELOG
WHERE FILENAME LIKE '%<changelog-file>%'
ORDER BY DATEEXECUTED DESC;

SELECT LOCKED, LOCKEDBY, LOCKGRANTED
FROM DATABASECHANGELOGLOCK;

LOCKED = true with an old LOCKGRANTED indicates a stale lock. A recorded MD5SUM that differs from the file indicates a checksum mismatch.

3. Compare changelog files to git history

On a developer machine with repo access:

git log --oneline -- src/main/resources/config/liquibase/changelog/
git diff HEAD~1 -- src/main/resources/config/liquibase/changelog/<file>.xml

Edits to files that are already present in DATABASECHANGELOG are the root cause of checksum mismatches.

4. Verify profile and contexts

JHipster uses spring profiles and spring.liquibase.contexts to select changelogs. Check application.yml / application-prod.yml:

spring:
  liquibase:
    contexts: prod
    change-log: classpath:config/liquibase/master.xml

Ensure the profile active on the failing instance matches the changelog set you expect. A missing file can be a packaging issue, not a DB issue.

Fixes tied to findings

Checksum mismatch

Development: revert the edit to the already executed file and create a new changeSet with a new id and author. Do not change the original changeSet.

Non-production only: after confirming no production impact, you can accept the new checksum. This is not safe for production.

Caution: Do not edit already executed Liquibase changelogs in production. Changes must be made in new changeSets to preserve auditability.

Stale changelog lock

Confirm no JHipster instance is currently running migrations. Check running pods, processes, and JHipster Registry registrations.

Release the lock manually with DB write permission:

UPDATE DATABASECHANGELOGLOCK SET LOCKED = FALSE, LOCKEDBY = NULL, LOCKGRANTED = NULL WHERE ID = 1;

Risk: releasing the lock while another instance is migrating can cause concurrent execution and data corruption. Only do this after confirming the environment is quiescent.

Missing changelog

Restore the file from version control to src/main/resources/config/liquibase/changelog and rebuild:

mvn clean package -Pprod

Verify the file is in the jar:

jar tf target/*.jar | grep liquibase/changelog

Then restart the service with the correct profile.

Duplicate changeSet id

Regenerate a unique id and author for the changeSet and move the logic to a new file. Reapply via a new migration. Never reuse an id that exists in DATABASECHANGELOG.

Escalation criteria

• Production database contains manual changes outside Liquibase. Requires DBA review before any checksum or lock operation.
• Lock release is unsafe due to concurrent writers or multiple JHipster microservices sharing a database.
• Migration requires data backfill, transformation, or rollback beyond clear-checksums or lock release.
• Multiple services share a database. Coordinate changes across teams to avoid cross-service changeSet collisions.

Verification

Start the application locally with the same profile and observe logs for Liquibase execution order and completion.

Query DATABASECHANGELOG to confirm the latest changeSet matches the files in src/main/resources/config/liquibase/changelog.

Run a clean build and package to verify changelog files are included in the jar and the application starts against a test database.

Limitations: This guide covers validation failures at startup. Runtime Liquibase errors during data migration, or issues with JHipster Registry service discovery, require separate diagnostics.