quarkusio/quarkus · error · IllegalStateException

MongoDBContainer should be started first

Error message

MongoDBContainer should be started first

What it means

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.

Source

Thrown at extensions/mongodb-client/deployment/src/main/java/io/quarkus/mongodb/deployment/DevServicesMongoProcessor.java:278

        @Override
        public void configure() {
            super.configure();
            if (useSharedNetwork) {
                return;
            }

            if (fixedExposedPort != null) {
                addFixedExposedPort(fixedExposedPort, MONGODB_INTERNAL_PORT);
            } else {
                addExposedPort(MONGODB_INTERNAL_PORT);
            }
        }

        @Override
        public String getReplicaSetUrl(String databaseName) {
            if (!isRunning()) {
                throw new IllegalStateException("MongoDBContainer should be started first");
            }
            String authority;
            if (useSharedNetwork) {
                authority = DevServicesHostUtil.formatHostAndPort(hostName, MONGODB_INTERNAL_PORT);
            } else {
                authority = DevServicesHostUtil.formatResolvedHostAndPort(getContainerId(), getHost(),
                        getMappedPort(MONGO_EXPOSED_PORT));
            }
            return "mongodb://" + authority + "/" + databaseName;
        }

        public String getEffectiveHost() {
            return useSharedNetwork ? hostName : super.getHost();
        }

        public Integer getEffectivePort() {
            return useSharedNetwork ? MONGODB_INTERNAL_PORT : getMappedPort(MONGO_EXPOSED_PORT);
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the step consuming getReplicaSetUrl depends on the build item that starts the container (order via @BuildStep @Consume)
2. Verify Dev Services actually started: do not set a fixed quarkus.mongodb.connection-string and expect dev-service URLs
3. Check container startup logs for failures (Docker/Podman not running, port conflicts)
4. Guard the call with isRunning() or wait for startup before requesting the URL

Example fix

// before
String url = devService.getReplicaSetUrl("mydb"); // throws if not started
// after
if (devService.isRunning()) {
    String url = devService.getReplicaSetUrl("mydb");
} else {
    throw new IllegalStateException("Dev service did not start; check Docker and config");
}

if (!devService.isRunning()) {
    throw new IllegalStateException("MongoDB dev service not started; check Docker and quarkus.mongodb.devservices.* config");
}
String url = devService.getReplicaSetUrl("db");

null

try {
    return devService.getReplicaSetUrl(db);
} catch (IllegalStateException e) {
    log.error("Dev Services MongoDB container not running", e);
    return null;
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Dev services for ${request.getName()} requires a startable s
• name cannot be null
• Can only sync state on the server side of remote dev mode
• All parameters have already been loaded, it is too late to c
• Dev services cannot be started without a deployment class lo

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