Testcontainers "permission denied ... /var/run/docker.sock" in CI

The daemon is running and the socket exists, but the user running the tests lacks permission to read or write it. The socket is owned by root or the docker group, and the test user is in neither.

What this error means

Startup fails with "Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: ... connect: permission denied". It is common on self-hosted runners and inside non-root job containers.

Got permission denied while trying to connect to the Docker daemon socket at
unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.43/info":
dial unix /var/run/docker.sock: connect: permission denied

Common causes

The test user is not in the docker group

The socket is group-owned by docker; a user outside that group cannot access it, so every Docker call is denied.

A mounted socket keeps host ownership inside a container

When the host socket is bind-mounted into a job container, its numeric owner may not match any group the in-container user belongs to.

How to fix it

Add the runner user to the docker group

1. On a self-hosted runner, add the service account to the docker group.
2. Restart the runner service so the new group membership takes effect.
3. Confirm with docker info run as that user before the test step.

sudo usermod -aG docker "$USER"
# restart the shell / runner service so the group applies

Match the socket group inside a job container

When mounting the socket, run the container as a user in a group whose GID matches the socket owner, or adjust permissions on the mounted socket.

docker run --group-add "$(stat -c '%g' /var/run/docker.sock)" ...

How to prevent it

• Provision self-hosted runner users into the docker group during setup.
• Match container user GID to the mounted socket owner when sharing the socket.
• Smoke-test with docker info as the exact test user before running the suite.

Related guides