{"record":{"id":"f016d821ee419d28","repo":"testcontainers/testcontainers-java","slug":"previous-attempts-to-find-a-docker-environment-failed-will","errorCode":null,"errorMessage":"Previous attempts to find a Docker environment failed. Will not retry. Please see logs and check configuration","messagePattern":"Previous attempts to find a Docker environment failed\\. Will not retry\\. Please see logs and check configuration","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java","lineNumber":229,"sourceCode":"                .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<>();\n\n        // Manually enforce priority independent of priority property of strategy\n        allStrategies.add(new TestcontainersHostPropertyClientProviderStrategy());\n        allStrategies.add(new EnvironmentAndSystemPropertyClientProviderStrategy());\n\n        // Next strategy to try out is the one configured using the Testcontainers configuration mechanism\n        loadConfiguredStrategy().ifPresent(allStrategies::add);\n\n        // Finally, add all other strategies ordered by their internal priority\n        strategies\n            .stream()\n            .sorted(Comparator.comparing(DockerClientProviderStrategy::getPriority).reversed())","sourceCodeStart":211,"sourceCodeEnd":247,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java#L211-L247","documentation":"getFirstValidStrategy caches a hard failure in the FAIL_FAST_ALWAYS flag: once one strategy-selection pass has already failed, all later calls throw this IllegalStateException immediately instead of retrying. It signals that Testcontainers already concluded no usable Docker environment exists, so re-attempts are pointless until the JVM's configuration is fixed.","triggerScenarios":"A second attempt to obtain a DockerClient (e.g. a second test class/container in the same JVM) after an earlier getFirstValidStrategy pass failed — Docker daemon down, DOCKER_HOST wrong, or socket permissions missing during the first pass.","commonSituations":"Docker Desktop not running; CI runner without Docker; user lacking group membership for /var/run/docker.sock; tests continuing after a first failed container startup.","solutions":["Ensure Docker is reachable before the JVM starts (docker ps must succeed) and restart the test JVM after fixing it","Fix DOCKER_HOST / ~/.testcontainers.properties and rerun the tests — the flag is per-JVM, so a restart clears it","Check earlier log lines for the concrete failure reasons recorded during the first strategy pass","On Linux, add your user to the docker group or enable rootless Docker to fix permission-related first failures"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Fail fast in setup if Docker is unavailable, before the JVM caches the failure\nProcess p = new ProcessBuilder(\"docker\", \"info\").inheritIO().start();\nif (p.waitFor(10, TimeUnit.SECONDS) && p.exitValue() != 0) {\n    throw new IllegalStateException(\"Docker daemon unreachable; start Docker before running tests\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    DockerClientFactory.instance().client();\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"Will not retry\")) {\n        // restart the JVM after fixing Docker; the flag is per-process\n    }\n    throw e;\n}","preventionTips":["Ensure `docker ps` works in the same environment/user before running tests","Fix the root cause from the first strategy attempt's log lines, then restart the JVM","In CI, add a Docker availability check as a pre-step"],"tags":["docker","environment","fail-fast","testcontainers"],"backgroundTag":"docker-daemon-unavailable","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"}