Docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock
An endpoint mismatch, a stopped daemon, or a missing socket mount. Resolve which of the three, then start, retarget, or mount.

Introduction & Quick Summary
Symptom. Every Docker client command fails before it reaches a container:
$ docker ps
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?The message names the socket the client tried, not why it failed. The daemon may be stopped, the client may be pointed at a socket that does not exist in this shell, or the socket may be inside a container that was never mounted.
Cause. docker is a thin client. It serialises your command and sends it over a Unix socket (or TCP, or SSH) to dockerd. The default endpoint is /var/run/docker.sock, but the effective endpoint is whatever --host, DOCKER_HOST, or the current docker context says. If nothing is listening at that path, the client cannot produce anything more specific than this message.
Fix. Establish three facts in order: which endpoint the client resolved, whether a daemon listens there, and whether your user may speak to it. Then start the daemon, correct the context, or mount the socket. The three common one-line outcomes:
sudo systemctl start docker # daemon simply not running
docker context use default # client pointed at the wrong endpoint
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock docker:cli ps # inside a containerThis guide covers each of them with the checks that distinguish them, because the same sentence appears for all.
Core Mechanics, Signatures & Reproducible Setup
The Docker CLI resolves its endpoint in this order, last one winning:
--host/-Hflag on the command.DOCKER_HOSTenvironment variable.DOCKER_CONTEXTenvironment variable.- The current context in
~/.docker/config.json("currentContext"). - The built-in
defaultcontext:unix:///var/run/docker.sock.
docker context ls prints every endpoint the client knows and docker context inspect shows one in full. The socket is an ordinary filesystem entry, so inspect it without Docker:
$ ls -l /var/run/docker.sock
srw-rw---- 1 root docker 0 Nov 19 09:12 /var/run/docker.sock
$ ss -xlp | grep docker.sock
u_str LISTEN 0 4096 /run/docker.sock 1234 * 0 * 0 users:(("dockerd",pid=1234,fd=7))srw-rw---- means "socket, owner root, group docker". No dockerd line in ss means nothing is listening, which is the case this error reports.
A reproducible setup that shows the failure on purpose:
# A machine with the daemon stopped
sudo systemctl stop docker
docker version # Client starts, then: Cannot connect ... (Server section missing)
docker ps # same message
# Start it again
sudo systemctl start docker
docker version | sed -n '/Server:/,/^$/p'The client always prints its own version first. A Client block followed by the error instead of a Server block means the binary is fine and only the connection failed.
Key Comparison Table
What the same error message can actually mean:
| Observation | Real cause | First command to run |
|---|---|---|
docker version fails after the Client block | No daemon at the resolved endpoint | systemctl status docker, then start it |
ls -l /var/run/docker.sock says No such file | Daemon never created the socket | Start the daemon; check journalctl -u docker |
Works under sudo, fails as your user | Socket group or permissions | Add the user to the docker group and re-login |
| Works in the terminal, fails in cron or systemd | Service has no DOCKER_HOST or no socket access | Set the context or DOCKER_HOST explicitly |
| Fails only inside a container | Socket not bind-mounted | Mount the socket or drop the socket from the design |
| Client | Default endpoint | Typical failure trigger |
|---|---|---|
| Docker Engine on Linux | unix:///var/run/docker.sock | Service stopped or disabled after reboot |
| Docker Desktop | user socket under ~/.docker/run | Desktop app closed, WSL integration off |
| Rootless Docker | $XDG_RUNTIME_DIR/docker.sock | Shell started without the rootless env |
| Remote daemon over SSH | ssh://user@host | Key auth fails and the client reports the socket |
| Docker over TLS | tcp://host:2376 | DOCKER_TLS_VERIFY and cert paths unset |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. Read the endpoint the client actually used
Before touching the daemon, ask the client where it went. The docker error message names /var/run/docker.sock even when DOCKER_HOST points elsewhere, which is what makes this error so misleading.
env | grep -E '^DOCKER_(HOST|CONTEXT|TLS|CERT_PATH)'
docker context ls
docker context show
docker info --format '{{.ServerVersion}}' 2>&1 | head -3An asterisk on desktop-linux when you expected a Linux host, or a DOCKER_HOST exported in .zshrc for a machine you no longer use, is the whole bug:
unset DOCKER_HOST
docker context use default2. Start the daemon and read its own complaint
On a systemd host, systemctl status docker shows the last exit reason, and journalctl -u docker -n 50 shows why it stopped. Two very common startup blockers on a fresh install:
sudo systemctl enable --now docker
sudo journalctl -u docker -n 50 --no-pagererror initializing graphdrivermeans the data root sits on an unsupported filesystem, often an overlay mount inside a container.pid file found, ensure docker is not runningmeans a staledocker.pidafter a hard reboot; the daemon usually recovers on the next start.
On a host without systemd (Alpine, a container image, WSL without it enabled), start sudo dockerd --debug directly and watch its output.
3. Inside a container: mount the socket or stop needing it
A container needs both the binary and the socket. An image that installs only the CLI reproduces this error exactly:
docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-u "$(id -u):$(id -g)" \
docker:cli psTwo traps follow. The container's user must be allowed to open the host socket, so pass your UID as above or add the group. And mounting the socket hands the container root-equivalent control of the host daemon; mount it only for trusted build or CI containers.
A Docker Compose service that shells out to Docker needs the same volume:
services:
runner:
image: docker:cli
volumes:
- /var/run/docker.sock:/var/run/docker.sockValidate the file before applying it rather than debugging YAML and sockets at once; a schema mistake in volumes and a wrong socket path produce confusingly similar failures. Format and check compose files with the Docker Compose formatter.
4. Docker Desktop, WSL2 and context switching
Docker Desktop creates its own context and socket under the user profile. Three states break it:
- The Desktop app is not running: start it and wait for "Engine running". The CLI cannot start the engine.
- WSL integration is off for your distribution: enable it in Desktop settings for that distro, then reopen the shell so the
dockershim appears. - A leftover
DOCKER_HOSTfrom a remote server shadows the Desktop context.docker context use desktop-linuxfixes the CLI, but an exported variable still wins over the context.
On WSL without Desktop, systemd is often absent, so systemctl start docker itself fails with "System has not been booted with systemd". Enable systemd in /etc/wsl.conf or start dockerd manually.
5. Rootless Docker has a different socket path
Rootless mode runs the daemon as your user, listening on $XDG_RUNTIME_DIR/docker.sock instead of /var/run/docker.sock. Commands run from a fresh shell or a cron job without XDG_RUNTIME_DIR fall back to the default context and hit the same error:
echo "$XDG_RUNTIME_DIR/docker.sock"
systemctl --user status docker
docker context ls | grep rootlessIn a systemd user unit or a cron entry, recreate the environment explicitly instead of relying on the login session:
export XDG_RUNTIME_DIR="/run/user/$(id -u)"
export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/docker.sock"6. Remote daemons through SSH and TLS
When the endpoint is remote, the same message appears if SSH cannot reach the host or the key is not accepted. Ask the client to be verbose:
DOCKER_HOST=ssh://deploy@10.0.4.12 docker -D ps-D prints the SSH command it built. If ssh deploy@10.0.4.12 docker system dial-stdio works alone, the wire is fine. For TLS, DOCKER_HOST, DOCKER_TLS_VERIFY=1, DOCKER_CERT_PATH and a matching server name must all be set; a missing one yields the generic socket error, not a handshake error.
Common Compilation/Runtime Mistakes & Version Gotchas
- Adding the user to the
dockergroup and expecting the current shell to change. Group membership applies to new sessions. Log out and back in, or usenewgrp docker. Until then the permission error keeps appearing. - Using
sudo dockerto confirm the daemon works, then forgetting the permission fix.sudoshows the daemon is alive; it does not make your user able to reach the socket. - Assuming a context change is local to one shell. It is stored in
~/.docker/config.jsonand applies to every shell for that user, including CI runners that reuse a home directory; check it withdocker context show. - Exporting
DOCKER_HOSTin a dotfile to test a remote host once. The variable outranks the context and stays until removed; keep remote endpoints as named contexts. - Expecting DOCKER_HOST to work inside
docker buildsteps. ARUNinstruction executes in a container without the host socket; use BuildKit's--mount=type=sshinstead. - Confusing this error with an API version mismatch. "client version 1.47 is too new" and "Cannot connect" are different failures; only the first is solved by upgrading the client.
When the daemon answers but a command still fails, the next diagnosis is usually configuration rather than connectivity: verify env files and shells with the environment variable inspector, and read the status code your client actually received using the HTTP status code reference.
Reference: Docker Engine security and the daemon socket and Docker contexts.
Official references
primary documentationThe Docker documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Docker guides
All Docker guidesDocker: exec user process caused: exec format error
An arm64 image on an amd64 host is a runtime failure, not a pull failure. Diagnose the platform, build for the target, publish multi-arch, and spot the script variant.
Docker Compose: bind: address already in use and Port Conflicts
A published port is a host socket, and two projects cannot own it. How to find the real owner, why an override file merged instead of replacing, and how to publish dynamically.
Alpine musl vs Debian slim: DNS Timeouts and Native Builds
musl rejects manylinux wheels and linux-x64-gnu prebuilds, so the installer starts compiling without a toolchain. And ndots:5 in Kubernetes adds five seconds per lookup.
Docker Compose Connection Refused: localhost vs Service DNS
localhost inside a container is that container. Compose resolves service names on a shared network, depends_on does not wait for readiness, and binding loopback breaks the rest.
More in Docker
All Docker guidesThe guides filed next to this one in Docker, in library order.