testcontainers/testcontainers-java · error · IllegalStateException

Setter can only be called before the container is running

Error message

Setter can only be called before the container is running

What it means

CouchbaseContainer throws this IllegalStateException when a configuration setter (bucket, credentials, services, quotas) is invoked after the container has already started. These settings must be applied while the container is stopped so they can be used to bootstrap the Couchbase node. Once isRunning() returns true, late mutation is rejected to avoid inconsistent server state.

Solutions

  1. Move all with*() configuration calls to before container.start().
  2. Build configuration into a fresh CouchbaseContainer instance instead of mutating a running one.
  3. If you need to run containers before the test body, use a static/singleton container pattern and configure it at declaration time.
  4. Catch IllegalStateException as a programming-error signal and fix call ordering rather than handling it at runtime.

Example fix

// before
CouchbaseContainer container = new CouchbaseContainer();
container.start();
container.withBucket(new BucketDefinition("my-bucket")); // throws
// after
CouchbaseContainer container = new CouchbaseContainer()
    .withBucket(new BucketDefinition("my-bucket"));
container.start();
Defensive patterns

Strategy: validation

Validate before calling

if (container.isRunning()) {
    throw new IllegalStateException("Configure the CouchbaseContainer before start()");
}
container.withBucket(bucket);

Prevention

When it happens

Trigger: Calling withCredentials(), withBucket(), withEnabledServices(), withServiceQuota(), withAnalyticsService(), or withEventingService() after container.start() (or after try-with-resources starts the container).

Common situations: Configuring the container inside a lifecycle hook that runs post-start, reusing a container instance across tests and reconfiguring it between tests, or setting a bucket inside an @Before callback that runs after 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/8228907104bdd827. Report an issue: GitHub.

Appendix: source

Thrown at modules/couchbase/src/main/java/org/testcontainers/couchbase/CouchbaseContainer.java:803

            String body = null;
            if (response.body() != null) {
                try {
                    body = response.body().string();
                } catch (IOException e) {
                    logger().debug("Unable to read body of response: {}", response, e);
                }
            }

            throw new IllegalStateException(message + ": " + response + ", body=" + (body == null ? "<null>" : body));
        }
    }

    /**
     * Checks if already running and if so raises an exception to prevent too-late setters.
     */
    private void checkNotRunning() {
        if (isRunning()) {
            throw new IllegalStateException("Setter can only be called before the container is running");
        }
    }

    /**
     * Helper method to perform a request against a couchbase server HTTP endpoint.
     *
     * @param port the (unmapped) original port that should be used.
     * @param path the relative http path.
     * @param method the http method to use.
     * @param body if present, will be part of the payload.
     * @param auth if authentication with the admin user and password should be used.
     * @return the response of the request.
     */
    private Response doHttpRequest(
        final int port,
        final String path,
        final String method,
        final RequestBody body,

View on GitHub (pinned to 8e549514e3)