{"record":{"id":"89f43229a5c176a0","repo":"testcontainers/testcontainers-java","slug":"exception-while-creating-sslsocketfactory","errorCode":null,"errorMessage":"Exception while creating SSLSocketFactory","messagePattern":"Exception while creating SSLSocketFactory","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java","lineNumber":177,"sourceCode":"\n        Callable<Socket> socketProvider;\n        SocketAddress socketAddress;\n        switch (dockerHost.getScheme()) {\n            case \"tcp\":\n            case \"http\":\n            case \"https\":\n                SocketFactory socketFactory = SocketFactory.getDefault();\n                SSLConfig sslConfig = transportConfig.getSslConfig();\n                if (sslConfig != null) {\n                    try {\n                        socketFactory = sslConfig.getSSLContext().getSocketFactory();\n                    } catch (\n                        KeyManagementException\n                        | UnrecoverableKeyException\n                        | NoSuchAlgorithmException\n                        | KeyStoreException e\n                    ) {\n                        log.warn(\"Exception while creating SSLSocketFactory\", e);\n                        return false;\n                    }\n                }\n                socketProvider = socketFactory::createSocket;\n                socketAddress = new InetSocketAddress(dockerHost.getHost(), dockerHost.getPort());\n                break;\n            case \"unix\":\n            case \"npipe\":\n                if (!new File(dockerHost.getPath()).exists()) {\n                    log.debug(\"DOCKER_HOST socket file '{}' does not exist\", dockerHost.getPath());\n                    return false;\n                }\n                socketProvider =\n                    () -> {\n                        switch (dockerHost.getScheme()) {\n                            case \"unix\":\n                                return UnixSocket.get(dockerHost.getPath());\n                            case \"npipe\":","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java#L159-L195","documentation":"Testcontainers' strategy test (DockerClientProviderStrategy.test) failed to build an SSLSocketFactory from the SSLContext derived from the strategy's SSL config. This happens when the TLS material (keystore/truststore, certs, algorithms) in DOCKER_HOST TLS settings is unreadable or unusable. The strategy is then marked invalid and skipped, so Testcontainers falls through to other strategies and may ultimately report it could not find a Docker environment.","triggerScenarios":"DOCKER_HOST uses tcp/https scheme with an SSL config (transportConfig.getSslConfig() != null, e.g. DOCKER_CERT_PATH pointing at client certs) and initializing the SSLContext throws KeyManagementException, UnrecoverableKeyException, NoSuchAlgorithmException, or KeyStoreException.","commonSituations":"DOCKER_CERT_PATH points to missing, corrupt, or password-protected key.pem/cert.pem files; wrong keystore/truststore passwords; certs generated for a different JVM or using unsupported algorithms (e.g. PKCS12 vs JKS, modern algorithms on old JVMs); partial TLS setup where only some client cert files exist.","solutions":["Regenerate the Docker client TLS certificates (openssl or `docker run --rm -v docker-certs:/certs alpine` style) so key.pem/cert.pem/ca.pem exist and are valid at DOCKER_CERT_PATH.","If TLS is not required (local daemon on tcp://localhost:2375), unset DOCKER_CERT_PATH and use a plain tcp:// or unix:// DOCKER_HOST.","Verify the key password matches what docker-java expects (DOCKER_TLS_VERIFY setup) and that the keystore algorithm is supported by your JVM (update JVM if NoSuchAlgorithmException on modern algorithms).","Ensure file permissions allow the JVM user to read the cert/key files."],"exampleFix":"// before\nexport DOCKER_HOST=tcp://docker.example.com:2376\nexport DOCKER_CERT_PATH=/stale/certs\n// after\nexport DOCKER_CERT_PATH=~/.docker  # directory containing ca.pem, cert.pem, key.pem\n# or drop TLS entirely for a local daemon:\nexport DOCKER_HOST=tcp://localhost:2375","handlingStrategy":"validation","validationCode":"// Before starting containers, verify the TLS material is loadable\nPath certPath = Paths.get(System.getenv().getOrDefault(\"DOCKER_CERT_PATH\", \"\"));\nif (System.getenv(\"DOCKER_HOST\") != null && System.getenv(\"DOCKER_HOST\").startsWith(\"https\")) {\n    if (!Files.isRegularFile(certPath.resolve(\"key.pem\")) ||\n        !Files.isRegularFile(certPath.resolve(\"cert.pem\")) ||\n        !Files.isRegularFile(certPath.resolve(\"ca.pem\"))) {\n        throw new IllegalStateException(\"DOCKER_CERT_PATH is missing key.pem/cert.pem/ca.pem: \" + certPath);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    Container<?> c = new GenericContainer(\"alpine\").withCreateContainerCmdModifier(cmd -> {});\n    c.start();\n} catch (IllegalStateException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Could not find a valid Docker environment\")) {\n        log.error(\"Docker TLS config invalid; check DOCKER_CERT_PATH\", e);\n    }\n}","preventionTips":["Keep DOCKER_CERT_PATH pointing at a directory with valid ca.pem, cert.pem, key.pem.","Test the setup once with `docker --tlsverify -H $DOCKER_HOST info` before running the test suite.","Never password-protect client keys in a way docker-java can't read, and align keystore format with your JVM."],"tags":["docker","tls","ssl","keystore","testcontainers"],"backgroundTag":"missing-credentials","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"}