{"record":{"id":"9029a4ab377a7e2f","repo":"quarkusio/quarkus","slug":"mongodbcontainer-should-be-started-first","errorCode":null,"errorMessage":"MongoDBContainer should be started first","messagePattern":"MongoDBContainer should be started first","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/mongodb-client/deployment/src/main/java/io/quarkus/mongodb/deployment/DevServicesMongoProcessor.java","lineNumber":278,"sourceCode":"\n        @Override\n        public void configure() {\n            super.configure();\n            if (useSharedNetwork) {\n                return;\n            }\n\n            if (fixedExposedPort != null) {\n                addFixedExposedPort(fixedExposedPort, MONGODB_INTERNAL_PORT);\n            } else {\n                addExposedPort(MONGODB_INTERNAL_PORT);\n            }\n        }\n\n        @Override\n        public String getReplicaSetUrl(String databaseName) {\n            if (!isRunning()) {\n                throw new IllegalStateException(\"MongoDBContainer should be started first\");\n            }\n            String authority;\n            if (useSharedNetwork) {\n                authority = DevServicesHostUtil.formatHostAndPort(hostName, MONGODB_INTERNAL_PORT);\n            } else {\n                authority = DevServicesHostUtil.formatResolvedHostAndPort(getContainerId(), getHost(),\n                        getMappedPort(MONGO_EXPOSED_PORT));\n            }\n            return \"mongodb://\" + authority + \"/\" + databaseName;\n        }\n\n        public String getEffectiveHost() {\n            return useSharedNetwork ? hostName : super.getHost();\n        }\n\n        public Integer getEffectivePort() {\n            return useSharedNetwork ? MONGODB_INTERNAL_PORT : getMappedPort(MONGO_EXPOSED_PORT);\n        }","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/mongodb-client/deployment/src/main/java/io/quarkus/mongodb/deployment/DevServicesMongoProcessor.java#L260-L296","documentation":"Dev Services for MongoDB starts a container lazily; the DevServicesBuildItem's getReplicaSetUrl requires the underlying MongoDBContainer to be running. Querying the replica set URL while the container has not started (or has stopped) throws IllegalStateException.","triggerScenarios":"Calling getReplicaSetUrl(databaseName) on the dev-services MongoDB build item when isRunning() is false — before startMongoDb completes, after container shutdown, or when the dev service was never started (disabled dev services).","commonSituations":"Build steps consuming the dev service URL before the start build step runs; Dev Services disabled (quarkus.mongodb.devservices.enabled=false) or skipped because a MongoDB URI is configured; container startup failure followed by URL lookup in a later step.","solutions":["Ensure the step consuming getReplicaSetUrl depends on the build item that starts the container (order via @BuildStep @Consume)","Verify Dev Services actually started: do not set a fixed quarkus.mongodb.connection-string and expect dev-service URLs","Check container startup logs for failures (Docker/Podman not running, port conflicts)","Guard the call with isRunning() or wait for startup before requesting the URL"],"exampleFix":"// before\nString url = devService.getReplicaSetUrl(\"mydb\"); // throws if not started\n// after\nif (devService.isRunning()) {\n    String url = devService.getReplicaSetUrl(\"mydb\");\n} else {\n    throw new IllegalStateException(\"Dev service did not start; check Docker and config\");\n}","handlingStrategy":"validation","validationCode":"if (!devService.isRunning()) {\n    throw new IllegalStateException(\"MongoDB dev service not started; check Docker and quarkus.mongodb.devservices.* config\");\n}\nString url = devService.getReplicaSetUrl(\"db\");","typeGuard":"null","tryCatchPattern":"try {\n    return devService.getReplicaSetUrl(db);\n} catch (IllegalStateException e) {\n    log.error(\"Dev Services MongoDB container not running\", e);\n    return null;\n}","preventionTips":["Declare @Consume/BuildProducer ordering so URL consumers run after container start","Do not set a fixed connection-string if you rely on dev-service URLs","Confirm Docker/Podman is running before integration builds"],"tags":["mongodb","dev-services","testcontainers","lifecycle"],"backgroundTag":"container-not-started","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"}