{"record":{"id":"906fff22d1155c8f","repo":"quarkusio/quarkus","slug":"error-starting-liquibase-906fff","errorCode":null,"errorMessage":"Error starting Liquibase","messagePattern":"Error starting Liquibase","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"extensions/liquibase/liquibase-mongodb/runtime/src/main/java/io/quarkus/liquibase/mongodb/runtime/LiquibaseMongodbRecorder.java","lineNumber":129,"sourceCode":"                    }\n\n                    try (Liquibase liquibase = liquibaseFactory.createLiquibase()) {\n                        if (liquibaseFactory.getConfiguration().cleanAtStart()) {\n                            liquibase.dropAll();\n                        }\n                        if (liquibaseFactory.getConfiguration().migrateAtStart()) {\n                            if (liquibaseFactory.getConfiguration().validateOnMigrate()) {\n                                liquibase.validate();\n                            }\n                            liquibase.update(liquibaseFactory.createContexts(), liquibaseFactory.createLabels());\n                        }\n                    }\n                } catch (UnsatisfiedResolutionException e) {\n                    //ignore, the DS is not configured\n                }\n            }\n        } catch (Exception e) {\n            throw new IllegalStateException(\"Error starting Liquibase\", e);\n        }\n    }\n}\n","sourceCodeStart":111,"sourceCodeEnd":133,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/liquibase/liquibase-mongodb/runtime/src/main/java/io/quarkus/liquibase/mongodb/runtime/LiquibaseMongodbRecorder.java#L111-L133","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the 'Caused by' chain to find the real failure (connection refused, changelog parse error, failed changeset)","Verify MongoDB connectivity (connection-string, credentials, network/TLS) before startup","Check quarkus.liquibase-mongodb.change-log points to a resource on the classpath and is valid","Fix or roll back the failing changeset; check DATABASECHANGELOG collections in the target DB for partial state","Set quarkus.liquibase-mongodb.enabled=false temporarily to start the app without migrations while debugging"],"exampleFix":"// before: changelog at wrong location\nquarkus.liquibase-mongodb.change-log=db/changelog.xml\n// after\nquarkus.liquibase-mongodb.change-log=liquibase/changelog/master.xml  // must exist under src/main/resources","handlingStrategy":"try-catch","validationCode":"// before app start: check changelog resource and Mongo reachability\nObjects.requireNonNull(getClass().getResource(\"/\" + changeLog), \"changelog not on classpath: \" + changeLog);\ntry (MongoClient c = MongoClients.create(connectionString)) {\n    c.getDatabase(\"admin\").runCommand(new BsonDocument(\"ping\", new BsonInt32(1)));\n}","typeGuard":null,"tryCatchPattern":"try {\n    liquibaseMongoDB.doStartActions();\n} catch (IllegalStateException e) {\n    Throwable root = e;\n    while (root.getCause() != null) root = root.getCause();\n    log.errorf(\"Liquibase startup failed (root cause %s: %s)\", root.getClass().getSimpleName(), root.getMessage());\n    throw e;\n}","preventionTips":["Always read the full 'Caused by' chain; this error is only a wrapper","Validate changelog files in CI (parse them) and keep them on src/main/resources","Test migrations against an ephemeral MongoDB container in the pipeline","Monitor DATABASECHANGELOG for failed/pending changesets before deploys","Pin and test the Liquibase-MongoDB driver versions when upgrading Quarkus"],"tags":["quarkus","mongodb","liquibase","startup"],"backgroundTag":"startup-migration-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}