testcontainers/testcontainers-java · error · ContainerLaunchException

Timed out waiting for container port to open ( host ports: …

Error message

Timed out waiting for container port to open ( host ports:  should be listening)

What it means

HostPortWaitStrategy checks that the container's mapped host ports accept TCP connections using ExternalPortListeningCheck/InternalPortListeningCheck futures. If any check fails, is cancelled, or times out, the strategy throws ContainerLaunchException listing the host and the ports that should have been listening. The oddly rendered message with blank host/ports means the values were empty at throw time.

Solutions

1. Increase timeout: `new HostPortWaitStrategy().withStartupTimeout(Duration.ofMinutes(3))`.
2. Verify the process inside the container listens on 0.0.0.0 and the correct port.
3. Confirm the ports passed to withExposedPorts/addExposedPort match the app's bind port.
4. Read container logs for early crashes that prevent the port from ever opening.

Example fix

// before
.waitingFor(new HostPortWaitStrategy());
// after
.waitingFor(new HostPortWaitStrategy().withStartupTimeout(Duration.ofMinutes(3)));

try { new HostPortWaitStrategy().withStartupTimeout(Duration.ofMinutes(3)).waitUntilReady(container); } catch (ContainerLaunchException e) { log.error("host ports never opened; logs: {}", container.getLogs()); throw e; }

When it happens

Trigger: waitUntilReady() submits liveness check futures and `future.get(0, TimeUnit.SECONDS)` throws CancellationException/ExecutionException/TimeoutException — port not yet bound inside the container, wrong exposed ports, or app slower than the timeout.

Common situations: App binds to localhost instead of 0.0.0.0, withExposedPorts missing the real port, slow JVM/DB startup, port mapping failures in constrained CI environments.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

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

Related errors

• Socket not listening yet:
• Timed out waiting for container to become healthy
• you cannot specify a value smaller than 1 ms
• Timed out waiting for URL to be accessible
• Timed out waiting for log output matching

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/wait/strategy/HostPortWaitStrategy.java:110

                        log.debug(
                            "External port check passed for {} mapped as {} in {}",
                            internalPorts,
                            externalLivenessCheckPorts,
                            Duration.between(now, Instant.now())
                        );
                        return true;
                    }
                ),
                startupTimeout.getSeconds(),
                TimeUnit.SECONDS
            );

            for (Future<Boolean> future : futures) {
                future.get(0, TimeUnit.SECONDS);
            }
        } catch (CancellationException | ExecutionException | TimeoutException e) {
            throw new ContainerLaunchException(
                "Timed out waiting for container port to open (" +
                waitStrategyTarget.getHost() +
                " ports: " +
                externalLivenessCheckPorts +
                " should be listening)"
            );
        }
    }

    private Set<Integer> getInternalPorts(Set<Integer> externalLivenessCheckPorts, List<Integer> exposedPorts) {
        return exposedPorts
            .stream()
            .filter(it -> externalLivenessCheckPorts.contains(waitStrategyTarget.getMappedPort(it)))
            .collect(Collectors.toSet());
    }

    public HostPortWaitStrategy forPorts(int... ports) {
        this.ports = ports;

View on GitHub (pinned to 8e549514e3)