Cannot Connect to Docker Daemon: Fix It Fast

It's 9 AM, you type docker ps, and the terminal answers with "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?" Nothing you changed yesterday explains it. Your images are still there, your compose file is untouched, and Docker worked fine on Friday. This error is the single most common Docker failure, and it's also one of the most misdiagnosed — engineers rebuild images, reinstall Docker, and reboot laptops before checking the three things that actually cause it.

The confusion comes from the error's many disguises. On Linux it mentions a unix socket. On Mac it may complain about a missing socket in ~/.docker/run. In CI it shows up as a TCP dial timeout to some builder host nobody remembers configuring. Underneath, every variant means the same thing: the docker CLI knocked on a door and nobody answered.

This guide walks through the four doors in order: a daemon that isn't running, a DOCKER_HOST pointing at the wrong place, socket permissions that lock you out, and a Docker context stuck on a remote engine. You'll get the exact commands to confirm each one, the fix that sticks, and the guards that stop it from ruining another morning.

The Client Is Fine — the Daemon Isn't Answering

Start with the mental model, because it makes every later step obvious. The docker binary is a thin HTTP client. dockerd is the server that owns all state: images, containers, volumes, networks. Between them sits either a unix socket (fast, local, file-permission gated) or a TCP/SSH endpoint (remote builders, CI fleets, Docker Desktop's VM forwarding). "Cannot connect" is purely a dial failure — the request never reached any Docker logic, so no image, registry, or Dockerfile theory can explain it.

Your first move is always docker info. Unlike docker ps, which hides the target, the info error names the address it tried: unix:///var/run/docker.sock, tcp://10.0.4.51:2376, or ssh://builder. That address is the entire diagnosis compressed into one line — it tells you whether you're fighting a local daemon, a stale remote, or a context you forgot. Pair it with docker version, which splits client vs server output: a client version with a failed server section proves the CLI is healthy and the daemon side is the problem.

The resolution order never changes: is anything listening, is the address correct, and are you allowed in. Check them in that order and you won't waste an hour fixing permissions on a daemon that isn't even running. Every section below maps to exactly one of those three questions.

dockerd Isn't Running: Start It on Linux, Mac, and Windows

The most common cause is also the simplest: dockerd isn't running. On Linux servers it usually means the service is stopped, crashed, or failed at boot — after an unattended upgrade, an OOM kill, or a daemon.json typo that prevents startup. On Mac and Windows it usually means Docker Desktop isn't launched, is still starting (the whale icon is animating), or is paused. Containers don't keep the daemon alive; the daemon keeps containers alive, so a dead daemon takes every docker command down with it.

On Linux, confirm with sudo systemctl status docker --no-pager: "active (running)" means look elsewhere, anything else means start it with sudo systemctl start docker and enable boot startup via sudo systemctl enable docker. If it refuses to start, read the real reason with sudo journalctl -u docker --since '15 min ago' — a JSON syntax error in /etc/docker/daemon.json is the classic silent killer, and journalctl prints the exact line. Validate the file with python3 -m json.tool /etc/docker/daemon.json before restarting.

On Docker Desktop, the daemon lives inside a VM and the socket is forwarded to ~/.docker/run/docker.sock. If the app isn't running, that socket simply doesn't exist. Launch the app, wait for the whale icon to stop animating, and confirm with ls ~/.docker/run/docker.sock. In CI, add a pre-flight docker info with a short timeout so a stopped daemon fails the job in seconds with a clear message instead of timing out 10 minutes into the build.

# Is the daemon alive? (Linux)
sudo systemctl status docker --no-pager
sudo systemctl start docker
sudo systemctl enable docker

# Why did it fail? Read the daemon's own logs
sudo journalctl -u docker --since '15 min ago' | tail -30

# A daemon.json typo kills startup silently — validate it
python3 -m json.tool /etc/docker/daemon.json

# Docker Desktop (Mac/Windows): socket exists only while the app runs
ls -l ~/.docker/run/docker.sock
ps aux | grep -i '[d]ocker desktop'

# Universal smoke test: server section present means connected
docker version
timeout 30 docker info

DOCKER_HOST Points Somewhere Wrong

DOCKER_HOST is an environment variable that overrides everything — contexts, defaults, all of it. Set it once for a remote builder session and forget to unset it, and every later docker command dials that old address: a decommissioned EC2 box, a builder VM you deleted, an SSH host whose key rotated. The error then looks like a network outage (TCP timeout, connection refused, SSH handshake failure) when it's really a leftover export in ~/.bashrc, /etc/environment, a direnv file, or a CI env block.

Diagnose in seconds: echo $DOCKER_HOST. Empty means the variable isn't your problem. A unix:// value should match a socket that exists on disk — check with ls -l on the path. A tcp:// value needs a reachable host and usually TLS certs via DOCKER_TLS_VERIFY and DOCKER_CERT_PATH; a connection refused means nothing listens there anymore. An ssh:// value needs working SSH credentials — test with plain ssh first, because the Docker CLI won't give you SSH-level diagnostics.

The fix is removal, not repair, when the target is retired: unset DOCKER_HOST in the current shell, then delete the export line from wherever it persists (shell rc files, /etc/environment, IDE run configs, pipeline YAML). If you genuinely use a remote daemon, prefer a named Docker context over a raw env var — contexts are visible in docker context ls and switchable, while env vars are invisible until they bite. Always re-verify with env | grep -i docker to prove nothing Docker-related lingers.

# Where is the CLI dialing?
echo "DOCKER_HOST=$DOCKER_HOST"
env | grep -i docker

# If it's a stale remote, drop it (current shell)
unset DOCKER_HOST
unset DOCKER_TLS_VERIFY
unset DOCKER_CERT_PATH

# Find where it persists across shells
cat ~/.bashrc ~/.zshrc /etc/environment 2>/dev/null | grep -n DOCKER
# Delete the export line from whichever file above matches, then:
exec $SHELL -l
env | grep -i docker   # should print nothing

# Legit remote daemon? Prefer a visible context over env vars
docker context create builder --docker host=ssh://deploy@10.0.4.60
docker context use builder
docker info | head -8

Socket Permissions: the docker Group and newgrp

On Linux the default socket /var/run/docker.sock is owned by root:docker with mode 660 — readable and writable only by root and members of the docker group. If your user isn't in that group, every command fails with "permission denied" or a dial error wrapping EACCES. This hits every new hire, every fresh VM, and every CI user that runs unprivileged. The trap: sudo docker ps works, so people conclude Docker is fine and their user config is broken — both true, and sudo-everything becomes the permanent workaround.

Fix it properly. Check the socket with ls -l /var/run/docker.sock and your membership with id -nG $USER. If docker is missing, run sudo usermod -aG docker $USER — the -a flag matters, since usermod -G without -a replaces all your groups and can lock you out of sudo. Then you must log out and back in, because group membership is evaluated at login. newgrp docker grants the group to the current shell only, which is fine for a quick test but evaporates when the shell closes — a classic reason the "fix" works in one terminal and fails in the next.

Understand the trade-off you're accepting: the docker group is effectively root-equivalent, since anyone who can talk to the daemon can mount / as a volume. That's fine for a personal dev box but worth a second thought on shared build machines, where rootless Docker or sudo-with-audit may fit better. Either way, never chmod 777 the socket — it silences today's error and hands every local user a root shell.

# Inspect the door and your badge
ls -l /var/run/docker.sock
id -nG "$USER"

# Join the docker group (-a appends; without it you lose sudo)
sudo usermod -aG docker "$USER"

# Group membership is read at login — log out and back in, then:
id -nG "$USER"   # docker should now appear
docker ps          # must work WITHOUT sudo

# Quick test in the current shell only (does not persist)
newgrp docker <<'EOF'
docker ps
EOF

Docker Contexts: the Remote Engine You Forgot

Docker contexts are named daemon endpoints — default for the local socket, desktop-linux for Docker Desktop, plus any remotes your team added for builders or staging hosts. The active context is sticky: switch to a remote for one deploy, and every docker command keeps dialing it until you switch back. When that remote gets deleted or its certs expire, you get daemon connection errors on a machine whose local daemon is perfectly healthy. docker context ls shows a star on the active entry; most people never look at it.

Run docker context ls the moment local checks pass but remote-style errors persist. Inspect the suspect with docker context inspect <name> and read the Host field under Endpoints. If it names a host that no longer exists, switch home with docker context use default on Linux (desktop-linux under Docker Desktop) and confirm docker info answers locally. Then clean up: docker context rm on every retired remote so the next engineer can't step on the same rake. Contexts live in ~/.docker/contexts, so a fix there follows your user across terminals — unlike env vars, there's exactly one place to look.

Make contexts boring infrastructure: name remotes after their purpose (prod-builder, staging), document the switch-back step in the runbook for any task that changes context, and prefer CI jobs that set context explicitly per step over relying on whatever the shared runner had active. A context-aware prompt segment (showing the active context in your shell) turns this whole failure class into something you see before it bites.

# Which daemon is active? The star marks it
docker context ls

# Read the endpoint of the suspect context
docker context inspect prod-builder --format '{{json .Endpoints}}'

# Switch back to the local daemon
docker context use default        # Linux servers
# docker context use desktop-linux  # Docker Desktop

docker context ls                 # star should be on the local entry
docker info | head -8             # proves local answers

# Remove retired remotes so nobody selects them again
docker context rm prod-builder staging-builder

Prove It's Fixed and Keep It Fixed

A fix you can't prove is a guess. Run the verification ladder: docker version shows both client and server sections, docker info prints storage driver and runtimes, and docker run --rm hello-world completes a full pull-and-run cycle against the daemon you intend to use. Each step exercises a deeper layer — dial, API, and actual container lifecycle — so passing all three means the connection is genuinely healthy, not just momentarily quiet. Record which daemon answered (docker info --format '{{.Name}}') so a passing test against the wrong engine doesn't fool you.

Then lock it in. On servers, systemctl enable docker plus a monitoring probe that runs docker info on a schedule catches the stopped-daemon case before users do. In CI, a pre-flight step with timeout 30 docker info fails fast with the resolved address in logs, turning future incidents into one-line diagnoses. For fleets, manage DOCKER_HOST and contexts through config management rather than shell files, and re-image long-lived runners after any migration so stale exports can't outlive the machines they were meant for.

Finally, write down your topology. A three-line note — where the daemon runs, which context is standard, who owns the remote builders — saves every future on-call from rediscovering it at 8 AM. The daemon connection is the front door of your whole container workflow; treat it like infrastructure with an owner, a monitor, and a runbook, and this error drops from incident to footnote.

# Three-layer proof: dial, API, full container lifecycle
docker version
docker info --format 'daemon={{.Name}} driver={{.Driver}}'
docker run --rm hello-world | head -5

# CI pre-flight: fail fast with the resolved address in logs
echo "daemon target: ${DOCKER_HOST:-default socket / active context}"
timeout 30 docker info > /dev/null || { echo 'daemon unreachable'; exit 1; }

# Server hardening: start on boot + scheduled probe
sudo systemctl enable docker
# cron: */5 * * * * /usr/bin/docker info >/dev/null 2>&1 || echo 'dockerd down' | mail -s 'docker alert' ops@example.com