"Cannot connect to the Docker daemon" — a diagnosis tree
⏱️ 2 min read
Cannot connect to the Docker daemon at unix:///var/run/docker.sock has three families of causes: the daemon isn't running, the client is looking at the wrong socket, or you lack permission on the socket. The tree below finds your branch fast.
Branch 1: is dockerd actually up?
systemctl status docker (Linux), or on macOS/Windows: is the Docker Desktop/OrbStack VM running? ps aux | grep dockerd tells you in one line. If it crashed, journalctl -u docker --since "1 hour ago" holds the reason — failed storage driver init and disk-full are the classics.
Branch 2: is the socket where the client thinks it is?
ls -l /var/run/docker.sock. Missing? Inside a container, the socket only exists if you mounted it (-v /var/run/docker.sock:/var/run/docker.sock). Over SSH, the daemon may listen on tcp:// with DOCKER_HOST unset. WSL adds its own twist: the daemon in WSL2 vs Docker Desktop shares nothing by default — set DOCKER_HOST or start the right one.
Branch 3: permissions
The socket is root-owned with group docker. id shows whether you're in the group — if not, sudo usermod -aG docker $USER then log out and back in (group changes don't apply to existing sessions; this trips up more people than any other step). Direct sudo docker ps working while plain docker ps fails is the signature of this branch.
Branch 4: the daemon is up but wedged
curl --unix-socket /var/run/docker.sock http://localhost/_ping should return OK. If it hangs, the daemon is alive but stuck — often a full disk (check df -h /var/lib/docker) or a deadlocked storage driver. Restarting dockerd is safe for container definitions, but running containers stop on most setups.
Once you've fixed it, keep a pristine environment to experiment in: a cheap hourly server — like these — lets you break and re-install dockerd until the tree is second nature.