testcontainers/testcontainers-java · error · InvalidConfigurationException

Could not find unix domain socket

Error message

Could not find unix domain socket

What it means

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.

Solutions

  1. Start the Docker daemon (systemctl start docker / start Docker Desktop)
  2. Set DOCKER_HOST to the actual socket path, e.g. unix://$HOME/.docker/run/docker.sock or unix:///var/snap.docker/... if using snap
  3. Mount the host socket into the container: -v /var/run/docker.sock:/var/run/docker.sock (with matching permissions)
  4. Let testcontainers pick another strategy — check output of 'docker context ls' and use the right DOCKER_HOST

Example fix

// before
export DOCKER_HOST=unix:///var/run/docker.sock // socket absent
// after
export DOCKER_HOST=unix://$HOME/.docker/run/docker.sock // Docker Desktop socket
Defensive patterns

Strategy: fallback

Validate before calling

java.nio.file.Path sock = java.nio.file.Path.of("/var/run/docker.sock");
boolean socketPresent = java.nio.file.Files.exists(sock);
if (!socketPresent) {
    // set DOCKER_HOST to an available socket or start the daemon before running tests
}

Type guard

static boolean dockerSocketExists() {
    return java.nio.file.Files.exists(java.nio.file.Path.of("/var/run/docker.sock"));
}

Try / catch

try {
    DockerClient c = DockerClientFactory.instance().client();
} catch (InvalidConfigurationException e) {
    if (e.getMessage().contains("Could not find unix domain socket")) {
        // fall back: start daemon or switch DOCKER_HOST to another socket
    } else throw e;
}

Prevention

When it happens

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

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

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

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

@Deprecated
public final class UnixSocketClientProviderStrategy extends DockerClientProviderStrategy {

    protected static final String DOCKER_SOCK_PATH = "/var/run/docker.sock";

    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() {

View on GitHub (pinned to 8e549514e3)