{"record":{"id":"dbc034d4cd4aa9c4","repo":"testcontainers/testcontainers-java","slug":"could-not-find-unix-domain-socket","errorCode":null,"errorMessage":"Could not find unix domain socket","messagePattern":"Could not find unix domain socket","errorType":"exception","errorClass":"InvalidConfigurationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/dockerclient/UnixSocketClientProviderStrategy.java","lineNumber":33,"sourceCode":"@Deprecated\npublic final class UnixSocketClientProviderStrategy extends DockerClientProviderStrategy {\n\n    protected static final String DOCKER_SOCK_PATH = \"/var/run/docker.sock\";\n\n    private static final String SOCKET_LOCATION = \"unix://\" + DOCKER_SOCK_PATH;\n\n    private static final int SOCKET_FILE_MODE_MASK = 0xc000;\n\n    public static final int PRIORITY = EnvironmentAndSystemPropertyClientProviderStrategy.PRIORITY - 20;\n\n    @Override\n    public TransportConfig getTransportConfig() throws InvalidConfigurationException {\n        Path dockerSocketFile = Paths.get(DOCKER_SOCK_PATH);\n        Integer mode;\n        try {\n            mode = (Integer) Files.getAttribute(dockerSocketFile, \"unix:mode\");\n        } catch (IOException e) {\n            throw new InvalidConfigurationException(\"Could not find unix domain socket\", e);\n        }\n\n        if ((mode & 0xc000) != SOCKET_FILE_MODE_MASK) {\n            throw new InvalidConfigurationException(\n                \"Found docker unix domain socket but file mode was not as expected (expected: srwxr-xr-x). This problem is possibly due to occurrence of this issue in the past: https://github.com/docker/docker/issues/13121\"\n            );\n        }\n\n        return TransportConfig.builder().dockerHost(URI.create(SOCKET_LOCATION)).build();\n    }\n\n    @Override\n    protected boolean isApplicable() {\n        return SystemUtils.IS_OS_LINUX || SystemUtils.IS_OS_MAC;\n    }\n\n    @Override\n    public String getDescription() {","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/dockerclient/UnixSocketClientProviderStrategy.java#L15-L51","documentation":"Thrown by UnixSocketClientProviderStrategy.getTransportConfig when /var/run/docker.sock does not exist or cannot be read as a unix socket attribute. This strategy is only applicable when the Docker daemon exposes a unix domain socket at the conventional path, so a missing socket means the strategy cannot be used.","triggerScenarios":"Running on Linux/macOS where DOCKER_SOCK_PATH (/var/run/docker.sock) does not exist, or Files.getAttribute(dockerSocketFile, 'unix:mode') throws IOException because the file is absent or unreadable.","commonSituations":"Docker daemon not installed/running; Docker Desktop socket configured elsewhere (e.g. ~/.docker/run/docker.sock); running in a container without mounting /var/run/docker.sock; snap-installed Docker using a different socket path.","solutions":["Start the Docker daemon (systemctl start docker / start Docker Desktop)","Set DOCKER_HOST to the actual socket path, e.g. unix://$HOME/.docker/run/docker.sock or unix:///var/snap.docker/... if using snap","Mount the host socket into the container: -v /var/run/docker.sock:/var/run/docker.sock (with matching permissions)","Let testcontainers pick another strategy — check output of 'docker context ls' and use the right DOCKER_HOST"],"exampleFix":"// before\nexport DOCKER_HOST=unix:///var/run/docker.sock // socket absent\n// after\nexport DOCKER_HOST=unix://$HOME/.docker/run/docker.sock // Docker Desktop socket","handlingStrategy":"fallback","validationCode":"java.nio.file.Path sock = java.nio.file.Path.of(\"/var/run/docker.sock\");\nboolean socketPresent = java.nio.file.Files.exists(sock);\nif (!socketPresent) {\n    // set DOCKER_HOST to an available socket or start the daemon before running tests\n}","typeGuard":"static boolean dockerSocketExists() {\n    return java.nio.file.Files.exists(java.nio.file.Path.of(\"/var/run/docker.sock\"));\n}","tryCatchPattern":"try {\n    DockerClient c = DockerClientFactory.instance().client();\n} catch (InvalidConfigurationException e) {\n    if (e.getMessage().contains(\"Could not find unix domain socket\")) {\n        // fall back: start daemon or switch DOCKER_HOST to another socket\n    } else throw e;\n}","preventionTips":["Ensure Docker Desktop/daemon is running before test suites","Mount /var/run/docker.sock when running tests inside containers","Set DOCKER_HOST explicitly for non-default socket locations (Docker Desktop, snap)","Add a preflight check in CI that 'docker info' succeeds"],"tags":["docker","unix-socket","file-not-found","testcontainers"],"backgroundTag":"file-not-found","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"}