Diagnose Docker socket permission errors on Windows

A /var/run/docker.sock error does not by itself prove that a Windows setup is using the wrong container type. Docker Desktop can run a Linux engine, WSL can provide Linux tooling, and a CLI can target a remote daemon. First identify where the client runs and which engine it is trying to reach.

docker context show
docker context ls
docker version

Check any DOCKER_HOST or DOCKER_CONTEXT overrides as well. Distinguish “permission denied” from “connection refused” and “file not found”: an inaccessible socket, a stopped engine, and the wrong path need different fixes.

Linux containers under Docker Desktop

A trusted Linux utility container can access a supported Docker socket mount:

docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock my-tool-image

The image must contain the intended client. When using WSL, confirm Desktop integration is enabled for that distribution and that the context points to the expected engine.

If the socket is present but permission is denied, inspect the container user's numeric UID/GIDs and the socket's permissions. A group with the same name is not sufficient when its numeric GID differs. Desktop security settings, rootless engines, and enhanced isolation can also change what is permitted. Do not solve this by making the socket world-writable.

Windows containers

For a compatible Windows engine, named pipes are used instead of a Linux filesystem socket. A trusted Windows utility image can use an explicit pipe mount:

docker run --rm -it --mount 'type=npipe,source=\\.\pipe\docker_engine,target=\\.\pipe\docker_engine' my-windows-tool-image

Use a Windows image compatible with the host and the correct endpoint for that engine. A pipe ACL or engine authorization problem is separate from Unix group permissions. Changing container mode does not convert Linux images into Windows images; Desktop maintains distinct engine environments.

Remote engine access

A configured SSH context avoids exposing an unauthenticated TCP endpoint. If using TCP, configure server and client certificate verification rather than merely selecting port 2376:

docker --host tcp://docker-host:2376 --tlsverify \
  --tlscacert ca.pem --tlscert cert.pem --tlskey key.pem ps

The certificates and reachable endpoint must already be configured. Port 2376 alone does not enable TLS or authorize a client.

FAQ

Is a read-only socket mount a read-only Docker API?

No. A filesystem :ro mount does not filter API operations sent through the socket. Access to a rootful daemon can provide host-level control. Use only trusted clients and an authorization layer when restricting operations is necessary.

Why does CI fail while a terminal works?

Compare the service account, environment, context, engine mode, and endpoint permissions. A Windows runner using a Linux mount recipe may need a different endpoint or a Linux runner, but that is a finding to verify rather than the explanation for every denial.

See daemon access protection, contexts, and container run.