{"record":{"id":"c06e6d400547a7a8","repo":"testcontainers/testcontainers-java","slug":"timed-out-waiting-for-container-port-to-open-host-ports","errorCode":null,"errorMessage":"Timed out waiting for container port to open ( host ports:  should be listening)","messagePattern":"Timed out waiting for container port to open \\( host ports:  should be listening\\)","errorType":"exception","errorClass":"ContainerLaunchException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/containers/wait/strategy/HostPortWaitStrategy.java","lineNumber":110,"sourceCode":"\n                        log.debug(\n                            \"External port check passed for {} mapped as {} in {}\",\n                            internalPorts,\n                            externalLivenessCheckPorts,\n                            Duration.between(now, Instant.now())\n                        );\n                        return true;\n                    }\n                ),\n                startupTimeout.getSeconds(),\n                TimeUnit.SECONDS\n            );\n\n            for (Future<Boolean> future : futures) {\n                future.get(0, TimeUnit.SECONDS);\n            }\n        } catch (CancellationException | ExecutionException | TimeoutException e) {\n            throw new ContainerLaunchException(\n                \"Timed out waiting for container port to open (\" +\n                waitStrategyTarget.getHost() +\n                \" ports: \" +\n                externalLivenessCheckPorts +\n                \" should be listening)\"\n            );\n        }\n    }\n\n    private Set<Integer> getInternalPorts(Set<Integer> externalLivenessCheckPorts, List<Integer> exposedPorts) {\n        return exposedPorts\n            .stream()\n            .filter(it -> externalLivenessCheckPorts.contains(waitStrategyTarget.getMappedPort(it)))\n            .collect(Collectors.toSet());\n    }\n\n    public HostPortWaitStrategy forPorts(int... ports) {\n        this.ports = ports;","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/wait/strategy/HostPortWaitStrategy.java#L92-L128","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase timeout: `new HostPortWaitStrategy().withStartupTimeout(Duration.ofMinutes(3))`.","Verify the process inside the container listens on 0.0.0.0 and the correct port.","Confirm the ports passed to withExposedPorts/addExposedPort match the app's bind port.","Read container logs for early crashes that prevent the port from ever opening."],"exampleFix":"// before\n.waitingFor(new HostPortWaitStrategy());\n// after\n.waitingFor(new HostPortWaitStrategy().withStartupTimeout(Duration.ofMinutes(3)));","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { new HostPortWaitStrategy().withStartupTimeout(Duration.ofMinutes(3)).waitUntilReady(container); } catch (ContainerLaunchException e) { log.error(\"host ports never opened; logs: {}\", container.getLogs()); throw e; }","preventionTips":["Bind internal services to 0.0.0.0.","Verify exposed port mappings with container.getMappedPort() in debug tests.","Allow generous startup timeouts in CI with slower machines."],"tags":["port","wait-strategy","timeout","connection-refused"],"backgroundTag":"connection-refused","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}