{"record":{"id":"cc0b6aae2207406a","repo":"testcontainers/testcontainers-java","slug":"socket-not-listening-yet","errorCode":null,"errorMessage":"Socket not listening yet: ","messagePattern":"Socket not listening yet: ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/containers/wait/internal/ExternalPortListeningCheck.java","lineNumber":33,"sourceCode":"@RequiredArgsConstructor\npublic class ExternalPortListeningCheck implements Callable<Boolean> {\n\n    private final ContainerState containerState;\n\n    private final Set<Integer> externalLivenessCheckPorts;\n\n    @Override\n    public Boolean call() {\n        String address = containerState.getHost();\n\n        externalLivenessCheckPorts\n            .parallelStream()\n            .forEach(externalPort -> {\n                try (Socket socket = new Socket()) {\n                    InetSocketAddress inetSocketAddress = new InetSocketAddress(address, externalPort);\n                    socket.connect(inetSocketAddress, 1000);\n                } catch (IOException e) {\n                    throw new IllegalStateException(\"Socket not listening yet: \" + externalPort);\n                }\n            });\n        return true;\n    }\n}\n","sourceCodeStart":15,"sourceCodeEnd":39,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/wait/internal/ExternalPortListeningCheck.java#L15-L39","documentation":"ExternalPortListeningCheck verifies, from the host, that the container's exposed ports accept TCP connections by opening Sockets with a 1-second connect timeout. If a connect raises IOException (connection refused, host unreachable, timeout) it throws IllegalStateException(\"Socket not listening yet: \" + port). It is used inside wait strategies, so it usually surfaces as a wait-strategy timeout.","triggerScenarios":"call() runs a parallelStream over external ports and socket.connect() fails for any of them — the service inside the container has not bound the port yet, crashed, or the mapped host port is wrong.","commonSituations":"App starts slower than the wait timeout, application binds to 127.0.0.1 inside the container instead of 0.0.0.0, wrong container port exposed via withExposedPorts.","solutions":["Increase the wait strategy timeout (`waitStrategy.withStartupTimeout(Duration)`).","Ensure the app inside the container listens on 0.0.0.0, not only localhost.","Verify withExposedPorts matches the ports the service actually binds.","Check container logs (`container.getLogs()`) for the app crashing at startup."],"exampleFix":"// before\ncontainer.waitingFor(new HostPortWaitStrategy()); // default ~60s\n// after\ncontainer.waitingFor(new HostPortWaitStrategy().withStartupTimeout(Duration.ofMinutes(3)));","handlingStrategy":"retry","validationCode":"// pre-check once the container is up:\nint port = container.getMappedPort(8080);\nboolean open = new Socket().connect(new InetSocketAddress(container.getHost(), port), 1000); // should not throw","typeGuard":null,"tryCatchPattern":"try { container.waitingFor(new HostPortWaitStrategy().withStartupTimeout(Duration.ofMinutes(3))); } catch (ContainerLaunchException e) { log.error(\"port never opened; logs: {}\", container.getLogs()); throw e; }","preventionTips":["Make services bind to 0.0.0.0 inside containers.","Match withExposedPorts to the ports the app actually binds.","Increase startup timeouts for slow-starting applications."],"tags":["port","socket","wait-strategy","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"}