Docker's least helpful message is also its most common one:

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

The text names the socket the client tried and nothing else. In practice that one sentence covers at least four unrelated situations: the daemon is stopped, the client resolved an endpoint you did not expect, your user has no permission on the socket, or the client is running inside a container where the socket was never mounted.

This is the order I check them in, because a careless fix for one of them quietly breaks another.

The client is a thin RPC shell

The docker binary does nothing on its own. It serialises your command and sends it to dockerd over a Unix socket, TCP, or SSH. The endpoint is resolved in this order, last match winning:

  • --host / -H on the command itself
  • the DOCKER_HOST environment variable
  • DOCKER_CONTEXT
  • currentContext in ~/.docker/config.json
  • the built-in default context: unix:///var/run/docker.sock

So the message can be accurate about the path and still misleading: it prints the default path even when your shell exported something else. Two commands settle what the client actually used:

env | grep -E '^DOCKER_(HOST|CONTEXT|TLS)' docker context ls 

An asterisk beside desktop-linux on a server, or a DOCKER_HOST left in a dotfile from a project you finished months ago, is the entire bug:

unset DOCKER_HOST docker context use default 

Fact 1: is anything listening on that path?

The socket is an ordinary filesystem entry, so inspect it without Docker at all:

ls -l /var/run/docker.sock ss -xlp | grep docker.sock 

srw-rw---- means "socket, owned by root, group docker". If ls says No such file, the daemon never created it, so the daemon is the problem, not the client. If the file is there but no dockerd line appears in ss, nothing is listening on it, which is exactly what the error reports.

Fact 2: start the daemon and read its own complaint

On a systemd host:

sudo systemctl enable --now docker sudo systemctl status docker sudo journalctl -u docker -n 50 --no-pager 

Two startup blockers are worth recognising on sight. error initializing graphdriver means the data root sits on a filesystem the storage driver will not use, which happens often when Docker runs inside an overlay-mounted container. pid file found, ensure docker is not running means a stale docker.pid after a hard reboot; the next start usually clears it.

On Alpine, in a container image, or in WSL with systemd disabled, systemctl itself fails. Run sudo dockerd --debug directly and read the log it prints.

Fact 3: may your user speak to it?

sudo docker ps succeeding and plain docker ps failing means the daemon is healthy and the permission is not. Add the user to the group and start a new session — group membership is applied at login:

sudo usermod -aG docker "$USER" newgrp docker # or log out and back in 

sudo proves the daemon is alive. It never fixes the permission.

Inside a container: mount the socket or stop needing it

An image that installs only the client reproduces this error precisely, because the socket is a host path:

docker run --rm \ -v /var/run/docker.sock:/var/run/docker.sock \ -u "$(id -u):$(id -g)" \ docker:cli ps 

Two traps follow. The container user needs permission on the host socket, hence the UID flag. And mounting that socket hands the container root-equivalent control of the host daemon, so mount it only for trusted build or CI containers. A Compose service that shells out to Docker needs the same volume:

services: runner: image: docker:cli volumes: - /var/run/docker.sock:/var/run/docker.sock 

Validate the Compose file before you debug YAML and sockets at the same time; a bad volumes key and a wrong socket path fail in equally confusing ways.

Docker Desktop, WSL and the context trap

Desktop does not use /var/run/docker.sock; it creates its own context and a socket under your user profile. Three states break it:

  1. The Desktop app is closed. The CLI cannot start the engine, so open the app and wait for "Engine running".
  2. WSL integration is off for your distribution. Enable it in Desktop settings, then reopen the shell so the docker shim appears.
  3. A stale DOCKER_HOST outranks the context. docker context use desktop-linux fixes the CLI, but the variable still wins.

On WSL without Desktop, systemctl start docker fails with "System has not been booted with systemd". Enable systemd in /etc/wsl.conf or start dockerd by hand.

Rootless Docker listens somewhere else

Rootless mode runs the daemon as your user on $XDG_RUNTIME_DIR/docker.sock, not /var/run/docker.sock. A cron job or systemd unit without that variable falls back to the default context and hits the same error:

export XDG_RUNTIME_DIR="/run/user/$(id -u)" export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/docker.sock" 

Set it explicitly in the unit or crontab instead of relying on a login session that is not there.

Remote daemons

When the endpoint is remote, the same sentence appears if SSH cannot reach the host or the key is not accepted. Ask the client to be verbose:

docker -D -H ssh://deploy-account-on-remote ps 

-D prints the SSH command it built. If the underlying SSH command works on its own, the wire is fine and the problem is Docker's side. For TLS, DOCKER_HOST, DOCKER_TLS_VERIFY=1 and DOCKER_CERT_PATH must all be set; a missing one produces the generic socket error rather than a handshake error.

Mistakes that keep the error alive

  • Adding the user to docker and expecting the current shell to change. It applies to new sessions.
  • Assuming a context change is local. It is written to the config file and applies to every shell for that user, CI included.
  • Exporting DOCKER_HOST to try a remote host once. The variable outranks contexts and outlives your memory of it. Keep remotes as named contexts.
  • Expecting DOCKER_HOST inside RUN steps. Build steps run in a container without the host socket; use BuildKit's SSH mount instead.
  • Confusing this with an API version mismatch. "client version is too new" is a different failure with a different fix.

Once the daemon answers and a command still fails, the problem has moved from connectivity to configuration. Verify what the process really sees in its environment, and read the status code your client actually received instead of guessing.

The longer version of this walkthrough, with the reproduction setup for each case, lives on my site: Docker daemon socket error.

References: Docker Engine security and the daemon socket, Docker contexts.