quarkusio/quarkus · critical · IllegalStateException

Error starting Liquibase

Error message

Error starting Liquibase

What it means

LiquibaseRecorder.doStartActions wraps startup migration (clean-at-start dropAll and migrate-at-start update) in a catch-all that rethrows as IllegalStateException('Error starting Liquibase'). Only self-explanatory InactiveBeanExceptions pass through untouched. This means Liquibase migration failed during application startup, and the real reason (changelog parse error, validation failure, DB lock, connection failure) is the wrapped cause.

Source

Thrown at extensions/liquibase/liquibase/runtime/src/main/java/io/quarkus/liquibase/runtime/LiquibaseRecorder.java:108

            }
            if (dataSourceConfig.migrateAtStart()) {
                var lockService = LockServiceFactory.getInstance()
                        .getLockService(liquibase.getDatabase());
                lockService.waitForLock();
                try {
                    if (dataSourceConfig.validateOnMigrate()) {
                        liquibase.validate();
                    }
                    liquibase.update(liquibaseFactory.createContexts(), liquibaseFactory.createLabels());
                } finally {
                    lockService.releaseLock();
                }
            }
        } catch (InactiveBeanException e) {
            // These exceptions should be self-explanatory
            throw e;
        } catch (Exception e) {
            throw new IllegalStateException("Error starting Liquibase", e);
        }
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

1. Read the 'Caused by' chain — LiquibaseException/ValidationFailure names the failing changeset.
2. Clear a stale changelog lock: DELETE FROM DATABASECHANGELOGLOCK; or use liquibase --force-release-locks.
3. Fix or roll back the edited changeset causing validation/checksum failure (run clearCheckSums only knowingly).
4. Verify quarkus.liquibase.change-log points to an existing resource and the datasource is reachable.
5. Pin or align the Liquibase version with your database engine's supported matrix.

Example fix

// before: edits an applied changeset -> checksum mismatch
<changeSet id="1" author="me">
  <sql>ALTER TABLE t ADD COLUMN b int</sql>
</changeSet>
// after: add a new changeset instead
<changeSet id="1" author="me">
  <sql>ALTER TABLE t ADD COLUMN a int</sql>
</changeSet>
<changeSet id="2" author="me">
  <sql>ALTER TABLE t ADD COLUMN b int</sql>
</changeSet>

// Pre-startup checks before migrate-at-start runs:
assert Files.exists(Path.of("src/main/resources/db/change-log.xml")) : "changelog missing";
// and check for a stale lock:
// SELECT COUNT(*) FROM DATABASECHANGELOGLOCK WHERE LOCKED = TRUE;

try {
    app.start(); // or run migrations via LiquibaseFactory directly
} catch (IllegalStateException e) {
    if ("Error starting Liquibase".equals(e.getMessage())) {
        Throwable cause = e.getCause();
        if (cause instanceof liquibase.exception.LockException) {
            log.error("Changelog lock held — clear DATABASECHANGELOGLOCK");
        } else if (cause instanceof liquibase.exception.ValidationFailedException) {
            log.error("Changeset validation failed: {}", cause.getMessage());
        }
    }
}

When it happens

Trigger: quarkus.liquibase.migrate-at-start or clean-at-start is true and liquibase.update()/dropAll()/validate() throws — changelog file missing or invalid XML/YAML, checksum validation mismatch, database changelog lock held, Liquibase-to-DB version incompatibility, or datasource connection failure.

Common situations: Changelog edited after being applied (checksum mismatch); two app instances contending on DATABASECHANGELOGLOCK; wrong changelog path in quarkus.liquibase.change-log; newer Liquibase bundled with Quarkus vs older DB; migration SQL error from schema drift.

Related errors

• Error while loading the liquibase changelogs: %s
• Config property 'quarkus.mongodb.database' must be defined w
• <errorMessage>.formatted(clientName) (required Liquibase Mon
• Error starting Liquibase
• Failed to start Quarkus

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/52591cfc9c201fef. Report an issue: GitHub.