What causes "MongoDBContainer should be started first" in testcontainers/testcontainers-java?

Start the container (container.start() or @Container with Testcontainers extension) before calling getReplicaSetUrl

testcontainers/testcontainers-java · error · IllegalStateException

MongoDBContainer should be started first

Error message

MongoDBContainer should be started first

What it means

MongoDBContainer.getReplicaSetUrl(databaseName) builds a replica-set connection string from the running container's connection string. If the container is not currently running, it throws this IllegalStateException because there is no valid endpoint to build a URL from.

Solutions

Start the container (container.start() or @Container with Testcontainers extension) before calling getReplicaSetUrl
Ensure the container reference used in the test is the same started instance (static + @Container pattern)
If building clients eagerly, defer client construction until after start

Example fix

// before
static MongoDBContainer mongo = new MongoDBContainer("mongo:6");
MongoClient client = MongoClients.create(mongo.getReplicaSetUrl("mydb")); // throws: not started
// after
@Container
static MongoDBContainer mongo = new MongoDBContainer("mongo:6");
@BeforeAll
static void init() {
    MongoClient client = MongoClients.create(mongo.getReplicaSetUrl("mydb"));
}

Defensive patterns

Strategy: validation

Validate before calling

if (!mongo.isRunning()) {
    mongo.start(); // or fail fast with a clear message
}
String url = mongo.getReplicaSetUrl("mydb");

Try / catch

try {
    String url = mongo.getReplicaSetUrl("mydb");
} catch (IllegalStateException e) {
    throw new IllegalStateException("MongoDBContainer not started; check @Container wiring", e);
}

Prevention

Use @Testcontainers with @Container static fields to enforce lifecycle
Never read container URLs in field initializers
Assert container.isRunning() in @BeforeAll before dependent setup

When it happens

Trigger: Calling getReplicaSetUrl(...) before start() has completed, after stop(), or from an accessor that runs before the container lifecycle hook (e.g. a static field initializer, @BeforeAll order issue, or a failed start that left the container stopped).

Common situations: Constructing a MongoClient in a field initializer before JUnit starts the container; reusing a container reference after a test class stopped it; a start() failure silently swallowed upstream.

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

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

Appendix: source

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

    /**
     * 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(final String databaseName) {
        if (!isRunning()) {
            throw new IllegalStateException("MongoDBContainer should be started first");
        }
        return getConnectionString() + "/" + databaseName;
    }

    private String[] buildMongoEvalCommand(final String command) {
        return new String[] {
            "sh",
            "-c",
            "mongosh mongo --eval \"" + command + "\"  || mongo --eval \"" + command + "\"",
        };
    }

    private void checkMongoNodeExitCode(final Container.ExecResult execResult) {
        if (execResult.getExitCode() != CONTAINER_EXIT_CODE_OK) {
            final String errorMessage = String.format("An error occurred: %s", execResult.getStdout());
            log.error(errorMessage);
            throw new ReplicaSetInitializationException(errorMessage);
        }

View on GitHub (pinned to 8e549514e3)