Cannot connect to the Docker daemon

The Docker CLI is a client. It does nothing itself — it sends commands to the Docker daemon over a socket. This error means the client could not reach that daemon.

Six realistic causes, and the exact wording of the error narrows it immediately.

Which error do you actually have?

That last row is the fastest diagnostic available. If sudo docker ps works and docker ps does not, skip to cause 2.

Cause 1 — The daemon is not running

sudo systemctl status docker
sudo systemctl start docker
sudo systemctl enable docker      # start it on boot

If it refuses to start, the journal says why:

sudo journalctl -u docker -n 50 --no-pager

The usual reasons are a malformed /etc/docker/daemon.json — a trailing comma is enough — a port conflict, or a full disk. Validate the config:

sudo dockerd --validate --config-file /etc/docker/daemon.json

Cause 2 — Your user is not in the docker group

Got permission denied while trying to connect to the Docker daemon socket
at unix:///var/run/docker.sock

The socket is owned by root:docker, so only root and members of the docker group can use it.

sudo usermod -aG docker $USER

Then log out and back in. Group membership is applied at login, so the change does nothing in your current shell. To test without logging out:

newgrp docker
docker ps

Verify it took effect:

id -nG        # should list "docker"
ls -l /var/run/docker.sock
# srw-rw---- 1 root docker 0 Sep 16 09:12 /var/run/docker.sock

A security note worth stating plainly: membership of the docker group is equivalent to root on that host. Anyone in it can start a privileged container mounting the host filesystem. That is a deliberate trade-off, not an oversight — on a shared or production machine, consider rootless Docker or Podman instead of handing out group membership.

Do not "fix" this with chmod 666 /var/run/docker.sock, which grants every user on the box root-equivalent access permanently.

Cause 3 — The CLI is pointed at the wrong daemon

Docker contexts select which daemon the CLI talks to. A leftover context pointing at a remote host or an old Docker Desktop socket produces this error even with a perfectly healthy local daemon.

docker context ls

NAME            DESCRIPTION                    DOCKER ENDPOINT
default         Current DOCKER_HOST based      unix:///var/run/docker.sock
desktop-linux * Docker Desktop                 unix:///home/me/.docker/desktop/docker.sock

The asterisk marks the active one. Switch back:

docker context use default

Also check for a stale environment variable, which overrides the context entirely:

echo $DOCKER_HOST
unset DOCKER_HOST

A DOCKER_HOST left over from an old eval $(minikube docker-env) is a common and confusing version of this — every command silently targets a cluster VM that may no longer exist.

Cause 4 — Docker Desktop is not running (macOS and Windows)

There is no background daemon until Docker Desktop starts. The CLI is installed and on your PATH regardless, so commands fail rather than reporting the application is closed.

Start Docker Desktop and wait for the whale icon to stop animating. Then:

docker info

If Desktop starts and immediately stops, the usual causes are insufficient allocated memory, a virtualisation feature disabled in BIOS, or on Windows, WSL 2 not installed. Resetting to factory defaults in Desktop's troubleshoot panel resolves a surprising share of stuck installs.

Cause 5 — WSL integration is off (Windows)

Docker Desktop runs the daemon in its own WSL distribution, and each distro must be explicitly allowed to reach it.

Settings → Resources → WSL Integration → enable your distro → Apply & Restart.

Without that, docker inside Ubuntu-on-WSL finds the CLI but no reachable socket.

Cause 6 — No daemon in CI

A CI job runs inside a container, which has no Docker daemon of its own. docker build fails here for a structural reason rather than a misconfiguration.

Two supported approaches:

Docker-in-Docker — attach a docker:dind service and point the client at it. Requires the runner to allow privileged mode, which effectively grants host access, so it is a poor choice on shared runners.

Kaniko or BuildKit rootless — builds images from a Dockerfile with no daemon and no privileged mode. This is the better default on shared or multi-tenant runners.

On GitLab CI specifically, a docker:dind service configured while the runner is not in privileged mode produces exactly this error, because the service container silently fails to start.

Quick diagnosis

# 1. Is there a daemon at all?
docker info

# 2. Is it a permissions problem?
sudo docker ps          # works with sudo, fails without → group membership

# 3. Am I pointed at the right daemon?
docker context ls
echo $DOCKER_HOST

# 4. Is the service up? (Linux)
systemctl status docker

A checklist

1. sudo docker ps works but docker ps does not → add yourself to the docker group, then log out and back in.
2. Linux, daemon down → systemctl start docker, and read journalctl -u docker if it refuses.
3. Check docker context ls and $DOCKER_HOST for a stale target.
4. macOS or Windows → is Docker Desktop actually running?
5. WSL → is integration enabled for your distro?
6. CI → there is no daemon; use dind with privileged mode, or Kaniko without it.

---

Frequently Asked Questions

How do I fix "Cannot connect to the Docker daemon"?

Work out which of two shapes you have. If sudo docker ps succeeds while docker ps fails, it is permissions — add yourself to the docker group with sudo usermod -aG docker $USER and log out and back in. If both fail, the daemon is not running: sudo systemctl start docker on Linux, or start Docker Desktop on macOS and Windows. If the daemon is definitely up, check docker context ls and $DOCKER_HOST for a stale target pointing somewhere else.

Why does docker work with sudo but not without it?

Because the Docker socket at /var/run/docker.sock is owned by root:docker, so only root and members of the docker group can use it. Adding yourself to that group fixes it, but the change only applies at login — running the usermod command and continuing in the same shell does nothing, which is why people often think it failed. Log out and back in, or run newgrp docker to pick it up in the current session.

Is adding my user to the docker group safe?

On a personal development machine, it is the normal thing to do. Be aware it is effectively equivalent to granting root on that host: anyone in the docker group can start a privileged container that mounts the host filesystem and escalate from there. On shared or production machines that is a genuine concern, and rootless Docker or Podman are better options. Never work around the permission error with chmod 666 on the socket, which grants the same power to every user permanently.

Why does Docker fail in my CI pipeline with this error?

Because CI jobs run inside a container, which has no Docker daemon of its own — this is structural rather than a misconfiguration. Either attach a Docker-in-Docker service and point the client at it, which requires the runner to permit privileged mode, or use Kaniko or rootless BuildKit, which build images from a Dockerfile without needing a daemon at all. Kaniko is the safer default on shared runners, since privileged mode there effectively grants host access to any job.

What is a Docker context and how can it cause this?

A context tells the CLI which daemon to talk to — a local socket, a remote host over SSH, or Docker Desktop's own socket. If the active context points somewhere unreachable, every command fails with this error even though a healthy daemon is running locally. Run docker context ls to see which is active, marked with an asterisk, and docker context use default to switch back. Also check $DOCKER_HOST, which overrides the context and is commonly left behind by eval $(minikube docker-env).

Docker Desktop is running but I still get this error on Windows. Why?

Almost certainly WSL integration. Docker Desktop runs the daemon inside its own WSL distribution, and each distro you use must be explicitly permitted to reach it — Settings, Resources, WSL Integration, enable your distro, then Apply and Restart. Without that, the docker command inside Ubuntu-on-WSL finds the CLI on the PATH but no reachable socket, producing this error despite Desktop appearing to run normally.