Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~6 min readDocker
#Docker#Linux#Troubleshooting#CLI
A glowing wall socket with an unplugged cable and a whale container, headline DOCKER SOCKET

Introduction & Quick Summary

Symptom. Every Docker client command fails before it reaches a container:

code
$ 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 container

This 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:

  1. --host / -H flag on the command.
  2. DOCKER_HOST environment variable.
  3. DOCKER_CONTEXT environment variable.
  4. The current context in ~/.docker/config.json ("currentContext").
  5. The built-in default context: 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:

bash
$ 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:

bash
# 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:

ObservationReal causeFirst command to run
docker version fails after the Client blockNo daemon at the resolved endpointsystemctl status docker, then start it
ls -l /var/run/docker.sock says No such fileDaemon never created the socketStart the daemon; check journalctl -u docker
Works under sudo, fails as your userSocket group or permissionsAdd the user to the docker group and re-login
Works in the terminal, fails in cron or systemdService has no DOCKER_HOST or no socket accessSet the context or DOCKER_HOST explicitly
Fails only inside a containerSocket not bind-mountedMount the socket or drop the socket from the design
ClientDefault endpointTypical failure trigger
Docker Engine on Linuxunix:///var/run/docker.sockService stopped or disabled after reboot
Docker Desktopuser socket under ~/.docker/runDesktop app closed, WSL integration off
Rootless Docker$XDG_RUNTIME_DIR/docker.sockShell started without the rootless env
Remote daemon over SSHssh://user@hostKey auth fails and the client reports the socket
Docker over TLStcp://host:2376DOCKER_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.

bash
env | grep -E '^DOCKER_(HOST|CONTEXT|TLS|CERT_PATH)' docker context ls docker context show docker info --format '{{.ServerVersion}}' 2>&1 | head -3

An 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:

bash
unset DOCKER_HOST docker context use default

2. 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:

bash
sudo systemctl enable --now docker sudo journalctl -u docker -n 50 --no-pager
  • error initializing graphdriver means the data root sits on an unsupported filesystem, often an overlay mount inside a container.
  • pid file found, ensure docker is not running means a stale docker.pid after 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 ps

Two 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.sock

Validate 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 docker shim appears.
  • A leftover DOCKER_HOST from a remote server shadows the Desktop context. docker context use desktop-linux fixes 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:

bash
echo "$XDG_RUNTIME_DIR/docker.sock" systemctl --user status docker docker context ls | grep rootless

In 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:

bash
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 docker group and expecting the current shell to change. Group membership applies to new sessions. Log out and back in, or use newgrp docker. Until then the permission error keeps appearing.
  • Using sudo docker to confirm the daemon works, then forgetting the permission fix. sudo shows 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.json and applies to every shell for that user, including CI runners that reuse a home directory; check it with docker context show.
  • Exporting DOCKER_HOST in 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 build steps. A RUN instruction executes in a container without the host socket; use BuildKit's --mount=type=ssh instead.
  • 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 documentation

The Docker documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Docker guides

More in Docker

All Docker guides

The guides filed next to this one in Docker, in library order.