testcontainers/testcontainers-java · error · ContainerLaunchException

Timed out waiting for URL to be accessible

Error message

Timed out waiting for URL to be accessible (%s should return HTTP %s)

What it means

HttpWaitStrategy wraps Unreliables.retryUntilTrue and throws ContainerLaunchException when the target URL never became accessible with the expected status within the startup timeout. The TimeoutException is the cause; the message shows the URI and the expected HTTP status(es).

Solutions

1. Inspect container logs (container.getLogs()) to see whether the app actually started
2. Increase the timeout: new HttpWaitStrategy().withStartupTimeout(Duration.ofMinutes(5))
3. Confirm the port and path are correct and exposed/published
4. Check Docker resource issues (low memory, slow disk) slowing startup

Example fix

// before
new HttpWaitStrategy().forPort(8080).forPath("/health");
// after
new HttpWaitStrategy().forPort(8080).forPath("/health").withStartupTimeout(Duration.ofMinutes(3));

// Pre-check reachability before starting the wait
ContainerState c = ...;
if (!c.isRunning()) throw new IllegalStateException("Container exited early: " + c.getLogs());

try {
    container.start();
} catch (ContainerLaunchException e) {
    if (e.getCause() instanceof TimeoutException) {
        System.err.println("Container logs: " + container.getLogs());
    }
    throw e;
}

When it happens

Trigger: The endpoint never returns an acceptable status code before .withStartupTimeout(...) (default 60s) elapses — wrong port, app crash-looping, or app taking longer than the timeout to start.

Common situations: Waiting on a port the container never exposes (missing exposedPorts/Wait.forListeningPort mismatch); JVM/app cold start slower than default timeout; container failed to start at all (check container logs); using https without .usingTls() against a plain-HTTP endpoint.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• you cannot specify a value smaller than 1 ms
• HTTP response code was
• Response: did not match predicate
• Timed out waiting for log output matching
• Timed out waiting for container to execute

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/wait/strategy/HttpWaitStrategy.java:319

                                    String responseBody = getResponseBody(connection);

                                    log.trace("Get response {}", responseBody);

                                    if (!responsePredicate.test(responseBody)) {
                                        throw new RuntimeException(
                                            String.format("Response: %s did not match predicate", responseBody)
                                        );
                                    }
                                }
                            } catch (IOException e) {
                                throw new RuntimeException(e);
                            }
                        });
                    return true;
                }
            );
        } catch (TimeoutException e) {
            throw new ContainerLaunchException(
                String.format(
                    "Timed out waiting for URL to be accessible (%s should return HTTP %s)",
                    uri,
                    statusCodes.isEmpty() ? HttpURLConnection.HTTP_OK : statusCodes
                ),
                e
            );
        }
    }

    private HttpURLConnection openConnection(final String uri) throws IOException, MalformedURLException {
        if (tlsEnabled) {
            final HttpsURLConnection connection = (HttpsURLConnection) new URL(uri).openConnection();
            if (allowInsecure) {
                // Create a trust manager that does not validate certificate chains
                // and trust all certificates
                final TrustManager[] trustAllCerts = new TrustManager[] {
                    new X509ExtendedTrustManager() {

View on GitHub (pinned to 8e549514e3)