{"record":{"id":"975253ce040a1877","repo":"testcontainers/testcontainers-java","slug":"docker-host-is-not-listening","errorCode":null,"errorMessage":"DOCKER_HOST {} is not listening","messagePattern":"DOCKER_HOST (.+?) is not listening","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java","lineNumber":217,"sourceCode":"                        }\n                    };\n                socketAddress = new InetSocketAddress(\"localhost\", 2375);\n                break;\n            default:\n                log.warn(\"Unknown DOCKER_HOST scheme {}, skipping the strategy test...\", dockerHost.getScheme());\n                return true;\n        }\n\n        try (Socket socket = socketProvider.call()) {\n            Awaitility\n                .await()\n                .atMost(TestcontainersConfiguration.getInstance().getClientPingTimeout(), TimeUnit.SECONDS) // timeout after configured duration\n                .pollInterval(Duration.ofMillis(200)) // check state every 200ms\n                .pollDelay(Duration.ofSeconds(0)) // start checking immediately\n                .untilAsserted(() -> socket.connect(socketAddress));\n            return true;\n        } catch (Exception e) {\n            log.warn(\"DOCKER_HOST {} is not listening\", dockerHost, e);\n            return false;\n        }\n    }\n\n    /**\n     * Determine the right DockerClientConfig to use for building clients by trial-and-error.\n     *\n     * @return a working DockerClientConfig, as determined by successful execution of a ping command\n     */\n    public static DockerClientProviderStrategy getFirstValidStrategy(List<DockerClientProviderStrategy> strategies) {\n        if (FAIL_FAST_ALWAYS.get()) {\n            throw new IllegalStateException(\n                \"Previous attempts to find a Docker environment failed. Will not retry. Please see logs and check configuration\"\n            );\n        }\n\n        List<String> configurationFailures = new ArrayList<>();\n        List<DockerClientProviderStrategy> allStrategies = new ArrayList<>();","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java#L199-L235","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Verify the daemon is running: `docker info` / `systemctl start docker` / start Docker Desktop.","Confirm DOCKER_HOST matches the daemon's actual address and port (`ss -ltn | grep docker` or `docker context ls`).","Test raw connectivity: `nc -vz <host> <port>` or `curl http://<host>:<port>/_ping`; fix firewall/security-group rules if blocked.","Increase the timeout via testcontainers configuration `client.ping.timeout` if the host is merely slow to respond.","On CI, ensure the job has a Docker environment (e.g. enable Docker-in-Docker, socket sharing, or a remote daemon address)."],"exampleFix":"// before\nDOCKER_HOST=tcp://localhost:2376  # daemon actually listens on 2375\n// after\nDOCKER_HOST=tcp://localhost:2375","handlingStrategy":"try-catch","validationCode":"// Pre-flight connectivity check before running Testcontainers\nString dh = System.getenv().getOrDefault(\"DOCKER_HOST\", \"unix:///var/run/docker.sock\");\njava.net.URI uri = java.net.URI.create(dh);\nif (\"tcp\".equals(uri.getScheme()) || \"http\".equals(uri.getScheme()) || \"https\".equals(uri.getScheme())) {\n    try (java.net.Socket s = new java.net.Socket()) {\n        s.connect(new java.net.InetSocketAddress(uri.getHost(), uri.getPort()), 2000);\n    } catch (IOException e) {\n        throw new IllegalStateException(\"Docker daemon not reachable at \" + dh + \" — is it running?\", e);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    new GenericContainer(DockerImageName.parse(\"alpine:3\")).start();\n} catch (IllegalStateException e) {\n    Assume.assumeFalse(\"Docker environment unavailable — skipping tests\",\n        e.getMessage() != null && e.getMessage().contains(\"Could not find a valid Docker environment\"));\n    throw e;\n}","preventionTips":["Run `docker info` as a pre-test gate in CI.","Keep DOCKER_HOST port in sync with the daemon's actual listen port (2375 vs 2376).","Open firewall/security-group rules for the daemon port on remote hosts.","Configure a generous `client.ping.timeout` in ~/.testcontainers.properties for slow hosts."],"tags":["docker","connection-refused","network","docker-host","testcontainers"],"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"}