GitLab CI "Cannot connect to the Docker daemon": Docker-in-Docker fixes

By Melih Toksari, developer of MergeBell · Updated · 4 min read

Short answer

A GitLab CI job that runs docker commands needs a Docker daemon, usually the docker:dind service, and the client and daemon must agree on address and TLS. "Cannot connect to the Docker daemon at tcp://docker:2375" usually means the client tries port 2375 without TLS while dind, since Docker 19.03, starts with TLS: set DOCKER_TLS_CERTDIR to /certs and share /certs/client, or turn TLS off with DOCKER_HOST tcp://docker:2375 and an empty DOCKER_TLS_CERTDIR. The unix:///var/run/docker.sock version means DOCKER_HOST isn't set. A dind service that never starts, shown as "no such host", usually means the runner isn't privileged. GitLab.com's hosted Linux runners support Docker-in-Docker with TLS.

The job runs docker build, and stops at once:

docker: Cannot connect to the Docker daemon at tcp://docker:2375. Is the docker daemon running?

The job’s container has the Docker client, but the daemon runs in a separate container: the docker:dind service. The client and the daemon must agree on where to connect and whether to use TLS. Here is a setup that works in GitLab 19.5, and the fix for each daemon error.

A setup that works

build:
  image: docker:24.0.5-cli
  services:
    - docker:24.0.5-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker info
    - docker build -t my-image .
  • On GitLab.com’s hosted Linux runners, the saas-linux ones that run untagged jobs, this works as it is: they support Docker-in-Docker with TLS.

  • On your own runner, Docker-in-Docker needs privileged = true, and TLS needs /certs/client shared between the job and the service:

    [runners.docker]
      image = "docker:24.0.5-cli"
      privileged = true
      volumes = ["/certs/client", "/cache"]

    Privileged mode turns off the container’s security protections, so give the runner a tag and send only Docker jobs to it.

  • Pin both images to the same version, as above. With docker:latest, a new release can break the job without warning.

The service is reachable as docker because GitLab names a service after its image. The client image’s entrypoint finds the certificates under /certs/client and connects to tcp://docker:2376 with TLS.

Without TLS

If you can’t change the runner’s volumes, turn TLS off on both sides:

variables:
  DOCKER_HOST: tcp://docker:2375
  DOCKER_TLS_CERTDIR: ""

The runner still has to be privileged.

What each error means

  • Cannot connect to the Docker daemon at tcp://docker:2375. Since Docker 19.03, dind starts with TLS, on port 2376, and the client tries 2375 without TLS. Use the TLS setup above, or turn TLS off on both sides.
  • Cannot connect to the Docker daemon at unix:///var/run/docker.sock. DOCKER_HOST isn’t set, so the client looks for a local socket. Set it, and the TLS variables if you use TLS. Use the official docker image; docker/compose images are obsolete.
  • lookup docker … no such host. The service didn’t start, or isn’t called docker: see the service doesn’t start.
  • cgroups: cgroup mountpoint does not exist: unknown. A dind image older than 20.10 runs on a host with Docker Engine 20.10 or later. Use a newer service, such as docker:24.0.5-dind.
  • x509: certificate signed by unknown authority. A custom or private certificate, such as Zscaler’s, isn’t installed. The daemon runs in the service container, so install it there before the daemon starts; GitLab’s troubleshooting page has an example. Where the certificate goes for the runner and for image pulls is in GitLab Runner x509 errors.
  • unauthorized: incorrect username or password. The job uses the deprecated CI_BUILD_TOKEN. Log in with $CI_REGISTRY_USER and $CI_REGISTRY_PASSWORD, below.

The unix:// error also hits old jobs that read DOCKER_PORT_2375_TCP, a variable from Docker’s legacy links, on runners with the FF_NETWORK_PER_BUILD feature flag. Set DOCKER_HOST explicitly.

To log in to your project’s container registry:

echo "$CI_REGISTRY_PASSWORD" | docker login "$CI_REGISTRY" -u "$CI_REGISTRY_USER" --password-stdin

If the login works but the push says denied, see GitLab container registry “denied”. If pulls fail with toomanyrequests, that’s Docker Hub’s pull limit: see GitLab CI and Docker Hub rate limits.

The service doesn’t start

error during connect: Post "https://docker:2376/v1.24/auth": dial tcp: lookup docker on 127.0.0.11:53: no such host
  • The runner isn’t privileged. The job log shows mount: permission denied (are you root?) among the service container’s logs. Set privileged = true in config.toml, and make sure the job’s tags send it to that runner.

  • The service has a longer name. A service image with a registry host, like registry.hub.docker.com/library/docker:24.0.5-dind, gets a hostname from its full name. Give it the name the client expects:

    services:
      - name: registry.hub.docker.com/library/docker:24.0.5-dind
        alias: docker

On the Kubernetes executor

By default, the Kubernetes executor doesn’t run image entrypoints, so set what the entrypoint would, and make the job wait for the daemon:

build:
  image: docker:24.0.5-cli
  services:
    - name: docker:24.0.5-dind
      variables:
        HEALTHCHECK_TCP_PORT: "2376"
  variables:
    DOCKER_HOST: tcp://docker:2376
    DOCKER_TLS_CERTDIR: "/certs"
    DOCKER_TLS_VERIFY: 1
    DOCKER_CERT_PATH: "$DOCKER_TLS_CERTDIR/client"
  script:
    - docker info

The runner needs privileged = true and an empty_dir volume mounted at /certs/client. Without the health check, a job that starts before the daemon is up gets the tcp://docker:2375 or 2376 error.

Without a privileged runner

  • Rootless BuildKit or Buildah build images without a Docker daemon. On your own runners they may still need a seccomp or AppArmor allowance in the runner’s security_opt. GitLab’s docs no longer recommend kaniko, which isn’t maintained.
  • Docker socket binding mounts the host’s /var/run/docker.sock into the job instead of running dind. It’s fast, but every job shares the host’s daemon: a job can remove other containers, including the runner’s own, and volume paths refer to the host.

On your phone

MergeBell shows a job’s log live, so you can see which of these errors a build hit before you’re back at a computer, and Retry reruns it on the free tier. A retry helps after a runner change, such as turning on privileged mode; a change to .gitlab-ci.yml or its includes needs a new pipeline. More on that in how to retry a failed GitLab pipeline.

Frequently asked questions

Why does GitLab CI say "Cannot connect to the Docker daemon at tcp://docker:2375"?

Since Docker 19.03, the docker:dind service starts with TLS, on port 2376, but the client is trying port 2375 without TLS. Either use TLS, with DOCKER_TLS_CERTDIR set to "/certs" and /certs/client shared between the containers, or turn TLS off with DOCKER_HOST set to tcp://docker:2375 and DOCKER_TLS_CERTDIR set to an empty string. On the Kubernetes executor, the job may also have started before the daemon was ready.

What does "Cannot connect to the Docker daemon at unix:///var/run/docker.sock" mean in GitLab CI?

The Docker client found no DOCKER_HOST, so it looked for a local socket, and the job's container has none. Set DOCKER_HOST, and the TLS variables if you use TLS, to point at the docker:dind service, and use the official docker image for the client; the docker/compose images are obsolete.

Does Docker-in-Docker work on GitLab.com?

Yes. GitLab.com's hosted Linux runners, the saas-linux ones, support Docker-in-Docker with TLS: use a docker CLI image, the matching docker:dind service and DOCKER_TLS_CERTDIR set to "/certs". On your own runners, Docker-in-Docker needs privileged = true in the runner's config.toml.

Why does my GitLab dind service fail with "no such host"?

The service didn't start, or isn't called docker. If the service logs show "mount: permission denied (are you root?)", the runner isn't privileged: set privileged = true in config.toml and send the job to that runner with tags. If the service image name includes a registry host, add alias: docker to the service.

How do I build Docker images in GitLab CI without a privileged runner?

Use rootless BuildKit or Buildah, which build images without a Docker daemon, though on your own runners they may need a seccomp or AppArmor allowance in the runner's security_opt. GitLab's docs no longer recommend kaniko, which isn't maintained any more. Docker socket binding avoids privileged mode too, but every job then shares the host's Docker daemon.

Sources

Checked against these pages on 4 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.

Do this from your phone with MergeBell

Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.

Get MergeBell for iPhoneGet MergeBell for Android

On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.