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

Call start() (or use @Container/@Testcontainers) before accessing the connection string

testcontainers/testcontainers-java · error · IllegalStateException

MongoDBContainer should be started first

Error message

MongoDBContainer should be started first

What it means

MongoDBAtlasLocalContainer.getDatabaseConnectionString(databaseName) appends the database name to the base connection string of the Atlas Local container. If the container is not running, it throws this IllegalStateException since there is no base connection string yet.

Solutions

Call start() (or use @Container/@Testcontainers) before accessing the connection string
Verify Docker is running and the container actually started
Defer MongoClient creation to a @BeforeAll that runs after container startup

Example fix

// before
MongoDBAtlasLocalContainer atlas = new MongoDBAtlasLocalContainer(...);
String url = atlas.getDatabaseConnectionString("app"); // throws
// after
MongoDBAtlasLocalContainer atlas = new MongoDBAtlasLocalContainer(...);
atlas.start();
String url = atlas.getDatabaseConnectionString("app");

Defensive patterns

Strategy: validation

Validate before calling

if (!atlas.isRunning()) {
    atlas.start();
}
String url = atlas.getDatabaseConnectionString("app");

Try / catch

try {
    String url = atlas.getDatabaseConnectionString("app");
} catch (IllegalStateException e) {
    throw new IllegalStateException("Start MongoDBAtlasLocalContainer before reading the connection string", e);
}

Prevention

Wire the container with @Container so startup is ordered before use
Check Docker availability in the environment first
Defer connection-string consumers until after startup

When it happens

Trigger: Calling getDatabaseConnectionString(...) before start(), after stop(), or in a context where the container start failed (e.g. Docker not available), or wiring the connection string before the Testcontainers extension starts the container.

Common situations: Using the Atlas Local container like a plain config object and reading the URL during test configuration loading; @BeforeAll ordering where the accessor runs before @Container startup.

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/f63553fe35ac8a33. Report an issue: GitHub.

Appendix: source

Thrown at modules/mongodb/src/main/java/org/testcontainers/mongodb/MongoDBAtlasLocalContainer.java:64

    /**
     * Gets a database specific connection string for the default {@value #MONGODB_DATABASE_NAME_DEFAULT} database.
     *
     * @return a database specific connection string.
     */
    public String getDatabaseConnectionString() {
        return getDatabaseConnectionString(MONGODB_DATABASE_NAME_DEFAULT);
    }

    /**
     * Gets a database specific connection string for a provided <code>databaseName</code>.
     *
     * @param databaseName a database name.
     * @return a database specific connection string.
     */
    public String getDatabaseConnectionString(final String databaseName) {
        if (!isRunning()) {
            throw new IllegalStateException("MongoDBContainer should be started first");
        }
        return baseConnectionString() + "/" + databaseName + "?" + DIRECT_CONNECTION;
    }
}

View on GitHub (pinned to 8e549514e3)