TeamCity "Cannot connect to the Docker daemon" on the agent in CI

By Kaveh Alemi·Latchkey

A Docker step or the Docker build feature on the agent tried to talk to the Docker daemon and could not. Either Docker is not running on the agent, or the agent user lacks permission to access the daemon socket.

What this error means

A Docker step fails with "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?" and the build stops.

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

Common causes

The Docker daemon is not running on the agent

The agent host has no running Docker service, so any Docker step or the Docker wrapper fails to connect.

The agent user cannot access the Docker socket

The agent process runs as a user not in the docker group, so it is denied access to /var/run/docker.sock.

How to fix it

Start Docker and grant socket access

1. Ensure the Docker service is running on the agent host.
2. Add the agent service user to the docker group so it can use the socket.
3. Restart the agent so the new group membership applies, then re-run.

sudo systemctl start docker
sudo usermod -aG docker teamcity-agent

Confirm the agent reports Docker capability

On the agent, the "Agent Parameters" should show dockerVersion; if absent, Docker is not detected. Fix the daemon or socket access so the Docker build feature works.

How to prevent it

• Provision agents with Docker running and the agent user in the docker group.
• Use agent requirements on dockerVersion so only Docker-capable agents run Docker builds.
• Bake Docker into the agent image instead of installing it per build.

Frequently asked questions

Related guides

References

• GitHub Actions documentation