{"record":{"id":"1769c9bcc88f20c1","repo":"testcontainers/testcontainers-java","slug":"found-docker-unix-domain-socket-but-file-mode-was-not-as","errorCode":null,"errorMessage":"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","messagePattern":"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","errorType":"exception","errorClass":"InvalidConfigurationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/dockerclient/UnixSocketClientProviderStrategy.java","lineNumber":37,"sourceCode":"\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() {\n        return \"local Unix socket (\" + SOCKET_LOCATION + \")\";\n    }\n\n    @Override","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/dockerclient/UnixSocketClientProviderStrategy.java#L19-L55","documentation":"Thrown by UnixSocketClientProviderStrategy.getTransportConfig when /var/run/docker.sock exists but its file mode is not that of a socket with rwxr-xr-x permissions (mode & 0xc000 != SOCKET_FILE_MODE_MASK). The path is either not a socket (e.g. a regular file or directory) or has unusual permissions, historically caused by docker/docker#13121.","triggerScenarios":"Files.getAttribute(dockerSocketFile, 'unix:mode') returns a mode whose socket-type bits (0xc000) don't match SOCKET_FILE_MODE_MASK — e.g. /var/run/docker.sock is a directory, a regular file, or a socket with unexpected permission bits after daemon restarts.","commonSituations":"A leftover regular file or mount point at /var/run/docker.sock after Docker crash/reinstall; permissions changed by root vs non-root daemons; the referenced historical docker issue where the socket's mode was wrong after daemon restart.","solutions":["Remove the bad file and restart the Docker daemon so it recreates the socket: sudo rm /var/run/docker.sock && sudo systemctl restart docker","Verify with 'ls -l /var/run/docker.sock' that it shows 'srwxr-xr-x' (a socket)","Point DOCKER_HOST at a correct socket if the daemon uses a different one","If hitting the historical docker issue (docker/docker#13121), upgrade the Docker daemon"],"exampleFix":"// shell\n// before: ls -l /var/run/docker.sock -> -rw-r--r-- (regular file)\nsudo rm /var/run/docker.sock && sudo systemctl restart docker\n// after: srwxr-xr-x","handlingStrategy":"try-catch","validationCode":"import static java.nio.file.attribute.PosixFilePermissions.*;\njava.nio.file.Path p = java.nio.file.Path.of(\"/var/run/docker.sock\");\n// verify it is a socket with expected mode before letting testcontainers use it\nif (java.nio.file.Files.exists(p)) {\n    String perms = java.nio.file.Files.getPosixFilePermissions(p).toString();\n    // sanity-check permissions; a directory/regular file at this path will fail in testcontainers\n}","typeGuard":"static boolean looksLikeDockerSocket(java.nio.file.Path p) {\n    try {\n        Object mode = java.nio.file.Files.getAttribute(p, \"unix:mode\");\n        return ((Integer) mode & 0xc000) == 0xc000; // socket type bits\n    } catch (Exception e) { return false; }\n}","tryCatchPattern":"try {\n    DockerClient c = DockerClientFactory.instance().client();\n} catch (InvalidConfigurationException e) {\n    if (e.getMessage().contains(\"file mode was not as expected\")) {\n        // recreate socket: remove file and restart docker daemon\n    } else throw e;\n}","preventionTips":["After Docker crash/reinstall, verify /var/run/docker.sock is 'srwxr-xr-x'","Restart the daemon to recreate the socket if permissions look wrong","Don't mount a regular file over /var/run/docker.sock in containers","Track docker/docker#13121; upgrade daemon if you hit it repeatedly"],"tags":["docker","unix-socket","permissions","testcontainers"],"backgroundTag":"permission-denied","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"}