{"record":{"id":"2102e6d90c4b19a5","repo":"testcontainers/testcontainers-java","slug":"failed-to-get-docker-client-for-imagename","errorCode":null,"errorMessage":"Failed to get Docker client for ${imageName}","messagePattern":"Failed to get Docker client for (.+?)","errorType":"exception","errorClass":"ContainerFetchException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/images/RemoteDockerImage.java","lineNumber":129,"sourceCode":"                    tryImagePullCommand(pullImageCmd, logger, dockerImageName, imageName, lastFailure, lastRetryAllowed)\n                );\n\n            if (dockerImageName.get() == null) {\n                final Exception lastException = lastFailure.get();\n                logger.error(\n                    \"Failed to pull image: {}. Please check output of `docker pull {}`\",\n                    imageName,\n                    imageName,\n                    lastException\n                );\n                throw new ContainerFetchException(\"Failed to pull image: \" + imageName, lastException);\n            }\n\n            logger.info(\"Image {} pull took {}\", dockerImageName.get(), Duration.between(startedAt, Instant.now()));\n            LocalImagesCache.INSTANCE.refreshCache(imageName);\n            return dockerImageName.get();\n        } catch (DockerClientException e) {\n            throw new ContainerFetchException(\"Failed to get Docker client for \" + imageName, e);\n        }\n    }\n\n    private Callable<Boolean> tryImagePullCommand(\n        PullImageCmd pullImageCmd,\n        Logger logger,\n        AtomicReference<String> dockerImageName,\n        DockerImageName imageName,\n        AtomicReference<Exception> lastFailure,\n        Instant lastRetryAllowed\n    ) {\n        return () -> {\n            try {\n                pullImage(pullImageCmd, logger);\n                dockerImageName.set(imageName.asCanonicalNameString());\n                return true;\n            } catch (InterruptedException | InternalServerErrorException e) {\n                // these classes of exception often relate to timeout/connection errors so should be retried","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/images/RemoteDockerImage.java#L111-L147","documentation":"RemoteDockerImage.resolve() catches DockerClientException raised by the Docker client (docker-java) after the pull attempt and rewraps it as ContainerFetchException 'Failed to get Docker client for <image>'. It indicates the Docker daemon/client interaction itself failed while resolving the image, not merely that the pull failed.","triggerScenarios":"DockerClientException thrown inside resolve() — typically the docker-java client reports an error from the daemon (e.g. daemon unreachable after retries, invalid response from daemon) while resolving/pulling the image.","commonSituations":"Docker daemon not running or not reachable (DOCKER_HOST misconfigured); docker-java client version incompatibility; daemon restarting mid-test; malformed DOCKER_HOST/tls config.","solutions":["Verify Docker is running: `docker info` works from the same environment","Check DOCKER_HOST / testcontainers docker.host config points to a valid daemon","Restart the Docker daemon and rerun the test","Check testcontainers/java-docker-client version compatibility; upgrade testcontainers","Inspect the cause chain (DockerClientException) for the daemon-side error detail"],"exampleFix":"// before\nexport DOCKER_HOST=tcp://localhost:2375 // daemon not listening -> DockerClientException\n// after\neval $(minikube docker-env) // or unset DOCKER_HOST to use default unix socket","handlingStrategy":"try-catch","validationCode":"// precheck that the daemon is reachable\nboolean reachable = new ProcessBuilder(\"docker\",\"info\").inheritIO().start().waitFor() == 0;\nif (!reachable) throw new IllegalStateException(\"Docker daemon not reachable; check DOCKER_HOST\");","typeGuard":"null","tryCatchPattern":"try {\n    new RemoteDockerImage(imageName).resolve(dockerClient);\n} catch (ContainerFetchException e) {\n    if (e.getCause() instanceof DockerClientException) {\n        throw new IllegalStateException(\"Docker client/daemon problem: \" + e.getCause().getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Verify `docker info` works in the same environment/CI job before tests","Do not override DOCKER_HOST unless you mean to; validate its URL format","Keep testcontainers and docker-java versions aligned","Restart Docker Desktop/daemon when it has been suspended or updated","Fail fast with an environment preflight check in CI"],"tags":["docker","docker-client","daemon"],"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"}