{"record":{"id":"72d69d804d24eb31","repo":"testcontainers/testcontainers-java","slug":"you-should-never-close-the-global-dockerclient","errorCode":null,"errorMessage":"You should never close the global DockerClient!","messagePattern":"You should never close the global DockerClient!","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/DockerClientFactory.java","lineNumber":205,"sourceCode":"        if (cachedClientFailure != null) {\n            log.debug(\"There is a cached checks failure - throwing\", cachedClientFailure);\n            throw cachedClientFailure;\n        }\n\n        if (client != null) {\n            return client;\n        }\n\n        final DockerClientProviderStrategy strategy = getOrInitializeStrategy();\n\n        client =\n            new DockerClientDelegate() {\n                @Getter\n                final DockerClient dockerClient = strategy.getDockerClient();\n\n                @Override\n                public void close() {\n                    throw new IllegalStateException(\"You should never close the global DockerClient!\");\n                }\n            };\n        log.info(\"Docker host IP address is {}\", strategy.getDockerHostIpAddress());\n\n        Info dockerInfo = strategy.getInfo();\n        log.debug(\"Docker info: {}\", dockerInfo.getRawValues());\n        Version version = client.versionCmd().exec();\n        log.debug(\"Docker version: {}\", version.getRawValues());\n        activeApiVersion = version.getApiVersion();\n\n        String serverInfo =\n            \"Connected to docker: \\n\" +\n            \"  Server Version: \" +\n            dockerInfo.getServerVersion() +\n            \"\\n\" +\n            \"  API Version: \" +\n            activeApiVersion +\n            \"\\n\" +","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/DockerClientFactory.java#L187-L223","documentation":"DockerClientFactory wraps the shared global DockerClient in a DockerClientDelegate whose close() throws this IllegalStateException. The client is a singleton shared across the JVM for all containers, so closing it would break every other consumer; the library deliberately forbids it.","triggerScenarios":"Calling close() on the DockerClient returned by DockerClientFactory.instance().client() (or any wrapper exposing the global client), e.g. in a finally block, try-with-resources, or a DI container disposing the client as a resource.","commonSituations":"Wrapping the client in try-with-resources by habit; shutting down a Spring/Guice context that registered the DockerClient as a Closeable bean; cleanup code that closes all Closeables in sight.","solutions":["Remove any close()/try-with-resources usage of the global DockerClient from DockerClientFactory.instance().client()","If using a DI framework, register the client without a destroy/close method","If you need a closable client, create your own DockerClient via DockerClientFactory or docker-java directly and close that one instead"],"exampleFix":"// before\ntry (DockerClient client = DockerClientFactory.instance().client()) {\n    client.inspectContainerCmd(id).exec();\n}\n// after\nDockerClient client = DockerClientFactory.instance().client();\nclient.inspectContainerCmd(id).exec(); // never close the global client","handlingStrategy":"try-catch","validationCode":"if (client == DockerClientFactory.instance().client()) { throw new AssertionError(\"do not close the shared DockerClient\"); }","typeGuard":"static boolean isSharedGlobalClient(DockerClient c) { return c instanceof DockerClientDelegate; }","tryCatchPattern":"try { client.close(); } catch (IllegalStateException e) { /* remove this close call entirely; never swallow into a retry */ }","preventionTips":["Never register DockerClientFactory.instance().client() as a Closeable/Disposable bean","Never wrap the global client in try-with-resources","Audit generic 'close everything' cleanup utilities for the DockerClient type"],"tags":["docker","lifecycle","resource-management","global-state"],"backgroundTag":"unsupported-operation","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"}