testcontainers/testcontainers-java · error · IllegalStateException

MongoDBContainer should be started first

Error message

MongoDBContainer should be started first

What it means

getReplicaSetUrl(databaseName) in org.testcontainers.mongodb returns connection string + '/' + databaseName, but only if the container is running. Otherwise it throws this IllegalStateException, since no connection string exists before startup.

Solutions

1. Ensure start() (or @Container) has run before calling getReplicaSetUrl
2. Use the static + @Testcontainers/@Container singleton pattern so the same instance is started
3. Check that container startup actually succeeded (no swallowed exceptions) before use

Example fix

// before
MongoDBContainer mongo = new MongoDBContainer("mongo:6");
String url = mongo.getReplicaSetUrl("orders"); // not started
// after
@Testcontainers
static MongoDBContainer mongo = new MongoDBContainer("mongo:6");
@Container
// start handled by extension; then in test:
String url = mongo.getReplicaSetUrl("orders");

if (!mongo.isRunning()) {
    throw new IllegalStateException("Call mongo.start() before getReplicaSetUrl()");
}

try {
    String url = mongo.getReplicaSetUrl("orders");
} catch (IllegalStateException e) {
    throw new IllegalStateException("MongoDBContainer lifecycle error — ensure @Container startup ran", e);
}

When it happens

Trigger: Invoking getReplicaSetUrl before container.start(), after stop(), or when start() failed (e.g. Docker daemon unavailable), or when the wrong (unstarted) container instance is referenced.

Common situations: Static client initialization before Testcontainers lifecycle; referencing a container after the test class torn it down; assuming a shared singleton container is already running.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• MongoDBContainer should be started first
• MongoDBContainer should be started first
• Changing startup timeout is not supported with mode
• Setter can only be called before the container is running
• Elasticsearch containerId is not available. In managed…

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/f9bc96759031b8b3. Report an issue: GitHub.

Appendix: source

Thrown at modules/mongodb/src/main/java/org/testcontainers/mongodb/MongoDBContainer.java:203

    /**
     * Gets a replica set url for the default {@value #MONGODB_DATABASE_NAME_DEFAULT} database.
     *
     * @return a replica set url.
     */
    public String getReplicaSetUrl() {
        return getReplicaSetUrl(MONGODB_DATABASE_NAME_DEFAULT);
    }

    /**
     * Gets a replica set url for a provided <code>databaseName</code>.
     *
     * @param databaseName a database name.
     * @return a replica set url.
     */
    public String getReplicaSetUrl(String databaseName) {
        if (!isRunning()) {
            throw new IllegalStateException("MongoDBContainer should be started first");
        }
        return getConnectionString() + "/" + databaseName;
    }
}

View on GitHub (pinned to 8e549514e3)