act_runner "Cannot connect to the Docker daemon" in CI

By Kaveh Alemi·Latchkey

act_runner in docker mode spins up a container per job by talking to the Docker daemon. If the daemon is not running or the socket is not mounted, container creation fails and every job errors before any step runs.

What this error means

Jobs fail immediately with a Docker daemon connection error. The runner log shows it could not reach /var/run/docker.sock when preparing the job container.

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 runner host

Docker mode needs a live daemon to create per-job containers; if dockerd is stopped, act_runner cannot start any container.

The docker socket is not available to the runner

When act_runner itself runs in a container, /var/run/docker.sock must be mounted in, or it has no daemon to talk to.

How to fix it

Start the Docker daemon on the host

1. Confirm docker mode is intended (labels use docker://).
2. Start and enable dockerd on the runner host.
3. Verify with docker info, then restart act_runner.

sudo systemctl enable --now docker
docker info
systemctl restart act_runner

Mount the docker socket into a containerized runner

If act_runner runs in Docker, bind-mount the host socket so it can drive the daemon.

docker run -d --name act_runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $PWD/config.yaml:/config.yaml \
  gitea/act_runner:latest

How to prevent it

• Run dockerd under systemd so it is up before act_runner starts.
• For containerized runners, always mount the docker socket.
• Monitor docker info health where docker-mode jobs run.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions