testcontainers/testcontainers-java · error · RuntimeException

Could not perform request against couchbase HTTP endpoint

Error message

Could not perform request against couchbase HTTP endpoint

What it means

CouchbaseContainer's doHttpRequest wraps all failures from the OkHttp call against a Couchbase server HTTP endpoint (REST/Query/Analytics services) in a RuntimeException with this message. It means the HTTP request itself failed (connection error, bad URL, I/O problem), not that the server returned an error status.

Solutions

  1. Check the wrapped cause exception for the real network failure (connection refused, unknown host, timeout).
  2. Ensure the container is running and fully initialized before triggering requests; rely on wait strategy completion.
  3. Verify container port bindings and that no proxy env vars (HTTP_PROXY) interfere with localhost requests.
  4. Retry after a short delay if hit during startup, since Couchbase services may not be listening yet.

Example fix

// before
container.start();
container.query("SELECT 1"); // may hit services not yet up
// after
container.start();
Awaitility.await().atMost(Duration.ofSeconds(30))
    .untilAsserted(() -> container.query("SELECT 1"));
Defensive patterns

Strategy: retry

Validate before calling

if (!container.isRunning()) {
    throw new IllegalStateException("Start the CouchbaseContainer before issuing HTTP requests");
}

Try / catch

try {
    container.query("SELECT 1");
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Could not perform request against couchbase HTTP endpoint")) {
        // inspect e.getCause(); back off and retry during startup
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Any internal request made by response(), queryResponse(), or stateResponse() where OkHttp's execute() throws: container not reachable yet, wrong port mapping, hostname resolution failure, or interrupted I/O.

Common situations: Querying the container before Couchbase services are fully up during startup; network/firewall issues in CI; connecting with a stale container reference after the container stopped.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

        final boolean auth
    ) {
        try {
            Request.Builder requestBuilder = new Request.Builder()
                .url("http://" + getHost() + ":" + getMappedPort(port) + path);

            if (auth) {
                requestBuilder = requestBuilder.header("Authorization", Credentials.basic(username, password));
            }

            if (body == null) {
                requestBuilder = requestBuilder.get();
            } else {
                requestBuilder = requestBuilder.method(method, body);
            }

            return HTTP_CLIENT.newCall(requestBuilder.build()).execute();
        } catch (Exception ex) {
            throw new RuntimeException("Could not perform request against couchbase HTTP endpoint ", ex);
        }
    }

    /**
     * Helper method which times an individual phase and logs it for debugging and optimization purposes.
     *
     * @param name the name of the phase.
     * @param toTime the runnable that should be timed.
     */
    private void timePhase(final String name, final Runnable toTime) {
        long start = System.nanoTime();
        toTime.run();
        long end = System.nanoTime();

        logger().debug("Phase {} took {}ms", name, TimeUnit.NANOSECONDS.toMillis(end - start));
    }

    /**

View on GitHub (pinned to 8e549514e3)