testcontainers/testcontainers-java · error · InvalidConfigurationException

Found docker unix domain socket but file mode was not as…

Error message

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

What it means

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.

Solutions

1. Remove the bad file and restart the Docker daemon so it recreates the socket: sudo rm /var/run/docker.sock && sudo systemctl restart docker
2. Verify with 'ls -l /var/run/docker.sock' that it shows 'srwxr-xr-x' (a socket)
3. Point DOCKER_HOST at a correct socket if the daemon uses a different one
4. If hitting the historical docker issue (docker/docker#13121), upgrade the Docker daemon

Example fix

// shell
// before: ls -l /var/run/docker.sock -> -rw-r--r-- (regular file)
sudo rm /var/run/docker.sock && sudo systemctl restart docker
// after: srwxr-xr-x

import static java.nio.file.attribute.PosixFilePermissions.*;
java.nio.file.Path p = java.nio.file.Path.of("/var/run/docker.sock");
// verify it is a socket with expected mode before letting testcontainers use it
if (java.nio.file.Files.exists(p)) {
    String perms = java.nio.file.Files.getPosixFilePermissions(p).toString();
    // sanity-check permissions; a directory/regular file at this path will fail in testcontainers
}

static boolean looksLikeDockerSocket(java.nio.file.Path p) {
    try {
        Object mode = java.nio.file.Files.getAttribute(p, "unix:mode");
        return ((Integer) mode & 0xc000) == 0xc000; // socket type bits
    } catch (Exception e) { return false; }
}

try {
    DockerClient c = DockerClientFactory.instance().client();
} catch (InvalidConfigurationException e) {
    if (e.getMessage().contains("file mode was not as expected")) {
        // recreate socket: remove file and restart docker daemon
    } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• Could not find unix domain socket
• Unexpected scheme
• Previous attempts to find a Docker environment failed. Will…
• containers are currently not supported
• Unknown transport type

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/1769c9bcc88f20c1. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/testcontainers/dockerclient/UnixSocketClientProviderStrategy.java:37

    private static final String SOCKET_LOCATION = "unix://" + DOCKER_SOCK_PATH;

    private static final int SOCKET_FILE_MODE_MASK = 0xc000;

    public static final int PRIORITY = EnvironmentAndSystemPropertyClientProviderStrategy.PRIORITY - 20;

    @Override
    public TransportConfig getTransportConfig() throws InvalidConfigurationException {
        Path dockerSocketFile = Paths.get(DOCKER_SOCK_PATH);
        Integer mode;
        try {
            mode = (Integer) Files.getAttribute(dockerSocketFile, "unix:mode");
        } catch (IOException e) {
            throw new InvalidConfigurationException("Could not find unix domain socket", e);
        }

        if ((mode & 0xc000) != SOCKET_FILE_MODE_MASK) {
            throw new InvalidConfigurationException(
                "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"
            );
        }

        return TransportConfig.builder().dockerHost(URI.create(SOCKET_LOCATION)).build();
    }

    @Override
    protected boolean isApplicable() {
        return SystemUtils.IS_OS_LINUX || SystemUtils.IS_OS_MAC;
    }

    @Override
    public String getDescription() {
        return "local Unix socket (" + SOCKET_LOCATION + ")";
    }

    @Override

View on GitHub (pinned to 8e549514e3)