testcontainers/testcontainers-java · error

DOCKER_HOST is not listening

Error message

DOCKER_HOST {} is not listening

What it means

The reachability test failed: Testcontainers opened a socket toward the DOCKER_HOST endpoint and could not connect within the configured ping timeout (Awaitility atMost with 200ms polling). This means nothing is listening at the address or it is unreachable, so the strategy is marked invalid.

Solutions

1. Verify the daemon is running: `docker info` / `systemctl start docker` / start Docker Desktop.
2. Confirm DOCKER_HOST matches the daemon's actual address and port (`ss -ltn | grep docker` or `docker context ls`).
3. Test raw connectivity: `nc -vz <host> <port>` or `curl http://<host>:<port>/_ping`; fix firewall/security-group rules if blocked.
4. Increase the timeout via testcontainers configuration `client.ping.timeout` if the host is merely slow to respond.
5. On CI, ensure the job has a Docker environment (e.g. enable Docker-in-Docker, socket sharing, or a remote daemon address).

Example fix

// before
DOCKER_HOST=tcp://localhost:2376  # daemon actually listens on 2375
// after
DOCKER_HOST=tcp://localhost:2375

// Pre-flight connectivity check before running Testcontainers
String dh = System.getenv().getOrDefault("DOCKER_HOST", "unix:///var/run/docker.sock");
java.net.URI uri = java.net.URI.create(dh);
if ("tcp".equals(uri.getScheme()) || "http".equals(uri.getScheme()) || "https".equals(uri.getScheme())) {
    try (java.net.Socket s = new java.net.Socket()) {
        s.connect(new java.net.InetSocketAddress(uri.getHost(), uri.getPort()), 2000);
    } catch (IOException e) {
        throw new IllegalStateException("Docker daemon not reachable at " + dh + " — is it running?", e);
    }
}

try {
    new GenericContainer(DockerImageName.parse("alpine:3")).start();
} catch (IllegalStateException e) {
    Assume.assumeFalse("Docker environment unavailable — skipping tests",
        e.getMessage() != null && e.getMessage().contains("Could not find a valid Docker environment"));
    throw e;
}

When it happens

Trigger: Socket connect to the DOCKER_HOST address (tcp host:port, unix socket path, or named pipe) throws (connection refused, timeout, no such file) within client-ping-timeout seconds, after which the catch block logs 'DOCKER_HOST {} is not listening'.

Common situations: Docker daemon not started or crashed; DOCKER_HOST points to a remote host with the daemon port closed; firewall/security group blocking port 2375/2376; DOCKER_HOST with custom port number wrong (e.g. daemon on 2375 but DOCKER_HOST says 2376); Docker Desktop not running; /var/run/docker.sock missing while strategy skipped existence check via tcp fallback.

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

• Unexpected scheme
• Elasticsearch container has no network configuration
• Elasticsearch container is not connected to the expected…
• Failed to connect Elasticsearch container to ad-hoc shared…
• Can't parse the default gateway IP

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java:217

                        }
                    };
                socketAddress = new InetSocketAddress("localhost", 2375);
                break;
            default:
                log.warn("Unknown DOCKER_HOST scheme {}, skipping the strategy test...", dockerHost.getScheme());
                return true;
        }

        try (Socket socket = socketProvider.call()) {
            Awaitility
                .await()
                .atMost(TestcontainersConfiguration.getInstance().getClientPingTimeout(), TimeUnit.SECONDS) // timeout after configured duration
                .pollInterval(Duration.ofMillis(200)) // check state every 200ms
                .pollDelay(Duration.ofSeconds(0)) // start checking immediately
                .untilAsserted(() -> socket.connect(socketAddress));
            return true;
        } catch (Exception e) {
            log.warn("DOCKER_HOST {} is not listening", dockerHost, e);
            return false;
        }
    }

    /**
     * Determine the right DockerClientConfig to use for building clients by trial-and-error.
     *
     * @return a working DockerClientConfig, as determined by successful execution of a ping command
     */
    public static DockerClientProviderStrategy getFirstValidStrategy(List<DockerClientProviderStrategy> strategies) {
        if (FAIL_FAST_ALWAYS.get()) {
            throw new IllegalStateException(
                "Previous attempts to find a Docker environment failed. Will not retry. Please see logs and check configuration"
            );
        }

        List<String> configurationFailures = new ArrayList<>();
        List<DockerClientProviderStrategy> allStrategies = new ArrayList<>();

View on GitHub (pinned to 8e549514e3)