testcontainers/testcontainers-java · error · IllegalStateException

Socket not listening yet:

Error message

Socket not listening yet: 

What it means

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.

Solutions

1. Increase the wait strategy timeout (`waitStrategy.withStartupTimeout(Duration)`).
2. Ensure the app inside the container listens on 0.0.0.0, not only localhost.
3. Verify withExposedPorts matches the ports the service actually binds.
4. Check container logs (`container.getLogs()`) for the app crashing at startup.

Example fix

// before
container.waitingFor(new HostPortWaitStrategy()); // default ~60s
// after
container.waitingFor(new HostPortWaitStrategy().withStartupTimeout(Duration.ofMinutes(3)));

// pre-check once the container is up:
int port = container.getMappedPort(8080);
boolean open = new Socket().connect(new InetSocketAddress(container.getHost(), port), 1000); // should not throw

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

When it happens

Trigger: 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.

Common situations: 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.

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.

Related errors

• Timed out waiting for container port to open ( host ports: …
• Services named do not exist, but wait conditions have been…
• This container's image does not have a healthcheck…
• Wait strategy failed. Container is removed
• Wait strategy failed. Container is dead

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/wait/internal/ExternalPortListeningCheck.java:33

@RequiredArgsConstructor
public class ExternalPortListeningCheck implements Callable<Boolean> {

    private final ContainerState containerState;

    private final Set<Integer> externalLivenessCheckPorts;

    @Override
    public Boolean call() {
        String address = containerState.getHost();

        externalLivenessCheckPorts
            .parallelStream()
            .forEach(externalPort -> {
                try (Socket socket = new Socket()) {
                    InetSocketAddress inetSocketAddress = new InetSocketAddress(address, externalPort);
                    socket.connect(inetSocketAddress, 1000);
                } catch (IOException e) {
                    throw new IllegalStateException("Socket not listening yet: " + externalPort);
                }
            });
        return true;
    }
}

View on GitHub (pinned to 8e549514e3)