testcontainers/testcontainers-java · error · IllegalStateException

Couchbase /pools did not return valid JSON

Error message

Couchbase /pools did not return valid JSON

What it means

During container startup CouchbaseContainer calls initializeIsEnterprise(), which GETs /pools from the management API and parses isEnterprise via Jackson. If the response body cannot be read as JSON (IOException from MAPPER.readTree), the container throws IllegalStateException because it cannot determine the edition and cannot validate service support.

Solutions

1. Ensure you use an official couchbase image tag and the container's exposed MGMT_PORT is reachable.
2. Retry the test — transient startup races usually disappear with a later Testcontainers version or longer wait strategy.
3. Check docker logs of the couchbase container and any HTTP proxy env vars (http_proxy/HTTP_PROXY) that could intercept container traffic.
4. Inspect what /pools actually returns (curl the mapped port) to see the malformed body.

// ensure container is started and no proxy intercepts container traffic
assertThat(System.getenv("HTTP_PROXY")).isNull();
ContainerExecResult r = container.execInContainer("curl", "-s", "localhost:8091/pools");
// response should start with '{' before the library parses it

try {
    container.start();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("did not return valid JSON")) {
        container.stop();
        container.start(); // retry once; often a startup race
    } else {
        throw e;
    }
}

When it happens

Trigger: The Couchbase node's management API returned a non-JSON body (HTML error page, empty/garbage body, proxy interception) on GET /pools while the container is initializing.

Common situations: Container not fully started yet (startup/probe race), a corporate proxy or firewall rewriting responses, wrong image tag that isn't actually a Couchbase server, or resource exhaustion making the server return an error page.

Understand the failure class

Background: "Invalid JSON response" and "Failed to parse response" errors: when an API answers 200 but the body isn't the JSON your library expected — this error's family across 28 libraries.

Related errors

• Couchbase /pools/default/nodeServices did not return valid…
• message: response, body=body
• The number of replicas must be between 0 and 3 (inclusive)
• Bucket quota cannot be less than 100MB!
• The provided service (service) has no quota to configure

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

Appendix: source

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

    /**
     * Before we can start configuring the host, we need to wait until the cluster manager is listening.
     */
    private void waitUntilNodeIsOnline() {
        new HttpWaitStrategy().forPort(MGMT_PORT).forPath("/pools").forStatusCode(200).waitUntilReady(this);
    }

    /**
     * Fetches edition (enterprise or community) of started container.
     */
    private void initializeIsEnterprise() {
        @Cleanup
        Response response = doHttpRequest(MGMT_PORT, "/pools", "GET", null, true);

        try {
            isEnterprise = MAPPER.readTree(response.body().string()).get("isEnterprise").asBoolean();
        } catch (IOException e) {
            throw new IllegalStateException("Couchbase /pools did not return valid JSON");
        }

        if (!isEnterprise) {
            if (enabledServices.contains(CouchbaseService.ANALYTICS)) {
                throw new IllegalStateException("The Analytics Service is only supported with the Enterprise version");
            }
            if (enabledServices.contains(CouchbaseService.EVENTING)) {
                throw new IllegalStateException("The Eventing Service is only supported with the Enterprise version");
            }
        }
    }

    /**
     * Initializes the {@link #hasTlsPorts} flag.
     * <p>
     * Community Edition might support TLS one happy day, so use a "supports TLS" flag separate from
     * the "enterprise edition" flag.
     */

View on GitHub (pinned to 8e549514e3)