quarkusio/quarkus · error · IllegalStateException

Error while loading the liquibase changelogs: %s

Error message

Error while loading the liquibase changelogs: %s

What it means

At build time, LiquibaseMongodbProcessor.liquibaseNativeLogicalPathMappings parses every configured changelog to discover logical-file-path aliases so native-image resource mappings can be generated. If any changelog cannot be parsed or read, it wraps the cause in an IllegalStateException with this message. It is a build/deployment-time failure, so the application fails to start rather than failing lazily at runtime.

Source

Thrown at extensions/liquibase/liquibase-mongodb/deployment/src/main/java/io/quarkus/liquibase/mongodb/deployment/LiquibaseMongodbProcessor.java:240

        ChangeLogParameters changeLogParameters = new ChangeLogParameters();
        ChangeLogParserFactory changeLogParserFactory = ChangeLogParserFactory.getInstance();
        LinkedHashSet<LogicalPhysicalAlias> allAliases = new LinkedHashSet<>();
        try (var classLoaderResourceAccessor = new ClassLoaderResourceAccessor(
                Thread.currentThread().getContextClassLoader())) {
            for (LiquibaseMongodbBuildTimeClientConfig buildConfig : liquibaseBuildConfig.clientConfigs().values()) {
                String changeLog = resolveChangeLog(buildConfig.changeLog(), buildConfig.searchPath());
                if (changeLog == null) {
                    continue;
                }
                ChangeLogParser parser = changeLogParserFactory.getParser(changeLog, classLoaderResourceAccessor);
                DatabaseChangeLog root = parser.parse(changeLog, changeLogParameters, classLoaderResourceAccessor);
                if (root != null) {
                    allAliases.addAll(LiquibaseChangeLogResourceDiscovery.scan(root).logicalPhysicalAliases());
                }
            }
        } catch (Exception ex) {
            throw new IllegalStateException(
                    "Error while loading the liquibase changelogs: %s".formatted(ex.getMessage()), ex);
        }

        byte[] mappingBytes = mergeLogicalPathMappingProperties(allAliases);
        if (mappingBytes != null) {
            generatedResources.produce(
                    new GeneratedResourceBuildItem(LiquibaseLogicalPathMappings.MONGODB_MAPPING_RESOURCE, mappingBytes));
            nativeImageResources
                    .produce(new NativeImageResourceBuildItem(LiquibaseLogicalPathMappings.MONGODB_MAPPING_RESOURCE));
        }
    }

    private byte[] mergeLogicalPathMappingProperties(LinkedHashSet<LogicalPhysicalAlias> aliases) {
        if (aliases.isEmpty()) {
            return null;
        }
        TreeMap<String, String> sorted = new TreeMap<>();
        for (LogicalPhysicalAlias alias : aliases) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Read the wrapped cause (ex.getMessage()) — it names the offending changelog and parse error; fix the referenced changelog file
2. Verify quarkus.liquibase-mongodb.change-log points to a file on the classpath (e.g. db/changelog/db.changelog-master.yaml) with correct spelling
3. Validate the changelog's XML/YAML/JSON syntax and that all <include>/<includeAll> targets exist
4. Test the changelog with standalone Liquibase update to confirm it parses
5. Check for Liquibase syntax not supported by the quarkus-liquibase-mongodb bundled Liquibase version and align versions

Example fix

// before
quarkus.liquibase-mongodb.change-log=conf/master.yaml
// after
quarkus.liquibase-mongodb.change-log=db/changelog/master.yaml

// Run before build: check the changelog exists and parses
String path = "db/changelog/master.yaml";
if (getClass().getClassLoader().getResource(path) == null) {
    throw new IllegalStateException("quarkus.liquibase-mongodb.change-log resource missing: " + path);
}
new Liquibase(path, new ClassLoaderResourceAccessor(), new MongoConnection()) // or standalone Liquibase CLI validate

try {
    quarkusBuild(); // or application startup
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Error while loading the liquibase changelogs")) {
        log.error("Fix changelog syntax/path: " + e.getCause(), e);
    }
    throw e;
}

When it happens

Trigger: Running the Quarkus build (augmentation) for a MongoDB app whose quarkus.liquibase-mongodb.change-log points to a missing, unreadable, or syntactically invalid YAML/XML/JSON changelog; the parser.parse() call throws and the processor rethrows as IllegalStateException.

Common situations: Typo in the changelog path; changelog references included files that don't exist; invalid YAML/XML syntax; changelog uses Liquibase features/attributes unsupported by the bundled Liquibase version; resource not on the build classpath.

Related errors

• Error starting Liquibase
• Config property 'quarkus.mongodb.database' must be defined w
• <errorMessage>.formatted(clientName) (required Liquibase Mon
• Mongo client named '%s' not found
• Error starting Liquibase

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