quarkusio/quarkus · critical · IllegalStateException

Error starting Liquibase

Error message

Error starting Liquibase

What it means

doStartActions wraps the entire Liquibase MongoDB bootstrap (CDI lookups, MongoClient resolution, Liquibase initialization and migration execution) in a single try/catch and rethrows any failure as IllegalStateException('Error starting Liquibase'). It is a wrapper error; the root cause (the chained exception) holds the real problem.

Source

Thrown at extensions/liquibase/liquibase-mongodb/runtime/src/main/java/io/quarkus/liquibase/mongodb/runtime/LiquibaseMongodbRecorder.java:129

                    }

                    try (Liquibase liquibase = liquibaseFactory.createLiquibase()) {
                        if (liquibaseFactory.getConfiguration().cleanAtStart()) {
                            liquibase.dropAll();
                        }
                        if (liquibaseFactory.getConfiguration().migrateAtStart()) {
                            if (liquibaseFactory.getConfiguration().validateOnMigrate()) {
                                liquibase.validate();
                            }
                            liquibase.update(liquibaseFactory.createContexts(), liquibaseFactory.createLabels());
                        }
                    }
                } catch (UnsatisfiedResolutionException e) {
                    //ignore, the DS is not configured
                }
            }
        } catch (Exception e) {
            throw new IllegalStateException("Error starting Liquibase", e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Read the 'Caused by' chain to find the real failure (connection refused, changelog parse error, failed changeset)
2. Verify MongoDB connectivity (connection-string, credentials, network/TLS) before startup
3. Check quarkus.liquibase-mongodb.change-log points to a resource on the classpath and is valid
4. Fix or roll back the failing changeset; check DATABASECHANGELOG collections in the target DB for partial state
5. Set quarkus.liquibase-mongodb.enabled=false temporarily to start the app without migrations while debugging

Example fix

// before: changelog at wrong location
quarkus.liquibase-mongodb.change-log=db/changelog.xml
// after
quarkus.liquibase-mongodb.change-log=liquibase/changelog/master.xml  // must exist under src/main/resources

// before app start: check changelog resource and Mongo reachability
Objects.requireNonNull(getClass().getResource("/" + changeLog), "changelog not on classpath: " + changeLog);
try (MongoClient c = MongoClients.create(connectionString)) {
    c.getDatabase("admin").runCommand(new BsonDocument("ping", new BsonInt32(1)));
}

try {
    liquibaseMongoDB.doStartActions();
} catch (IllegalStateException e) {
    Throwable root = e;
    while (root.getCause() != null) root = root.getCause();
    log.errorf("Liquibase startup failed (root cause %s: %s)", root.getClass().getSimpleName(), root.getMessage());
    throw e;
}

When it happens

Trigger: Any failure while running Liquibase migrations at application startup: unreachable MongoDB server, bad connection string, invalid changelog XML/YAML/JSON, missing changelog file, SQL/Mongo syntax error in a changeset, or the nested 'Mongo client named ... not found' error.

Common situations: MongoDB not running or wrong port; changelog path typo in quarkus.liquibase-mongodb.change-log; a changeset failing mid-run after a partial deploy; version-upgrade breaking Liquibase change log parsing; native-image missing changelog resources.

Related errors

• Config property 'quarkus.mongodb.database' must be defined w
• <errorMessage>.formatted(clientName) (required Liquibase Mon
• Mongo client named '%s' not found
• Failed to start Quarkus
• Quarkus failed to start up

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