Testcontainers "Cannot connect to the Docker daemon at unix:///var/run/docker.sock" in CI

The Docker client knows which socket to use but connecting to it fails: the daemon is not running, or in a Docker-in-Docker job the container has no daemon and no host socket mounted. Nothing can start until a daemon answers.

What this error means

The job fails with "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?" It is common when tests run inside a container that lacks its own daemon.

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

Common causes

Tests run in a container with no daemon

A job using a container: image has its own filesystem but no Docker daemon inside it, so the socket path resolves to nothing.

The host socket is not mounted into the container

To use the host daemon from inside a container you must mount /var/run/docker.sock; without the mount the client has nothing to connect to.

How to fix it

Mount the host Docker socket into the job container

Bind the host socket so the client inside the container talks to the host daemon (socket sharing), which Testcontainers supports.

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: maven:3-eclipse-temurin-21
      volumes:
        - /var/run/docker.sock:/var/run/docker.sock

Or run tests directly on the runner host

The simplest reliable option is to skip the job container and run on ubuntu-latest, where the daemon is already running.

jobs:
  test:
    runs-on: ubuntu-latest   # no container: block

How to prevent it

• Prefer running Testcontainers directly on the runner host over inside a job container.
• If a job container is required, mount /var/run/docker.sock explicitly.
• Verify with docker info inside the exact environment your tests run in.

Related guides