🚨 Docker Error Guide: 'dial unix /var/run/docker.sock: connect: connection refused'

Overview

The Docker client cannot talk to the daemon over its Unix socket:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
dial unix /var/run/docker.sock: connect: connection refused

The Docker CLI is a thin client; all real work happens in the daemon (dockerd), reached through the socket at /var/run/docker.sock. connection refused means the socket file exists but nothing is accepting connections on it — the daemon is stopped, crashed, or still starting. (Contrast this with no such file or directory, which means the socket is missing entirely.) It is an availability problem, not a Docker-command problem.

Symptoms

• Every docker command (docker ps, docker build, docker compose up) fails with connection refused.
• systemctl status docker shows the service inactive, failed, or activating.
• The socket file exists (ls -l /var/run/docker.sock succeeds) but connections are refused.
• Inside CI or Docker-in-Docker, the sidecar daemon has not finished starting.
• After a host reboot, Docker did not come up because it was not enabled.

Common Root Causes

• The daemon is stopped. dockerd is not running, so nothing listens on the socket.
• The daemon crashed on startup — a bad /etc/docker/daemon.json, a storage-driver problem, or a corrupt state prevents it from binding the socket.
• Docker is not enabled at boot, so after a reboot the socket exists (from the socket unit) but no daemon accepts connections.
• Permission issues for non-root users not in the docker group (often surfaces as permission denied, sometimes conflated with connection failures).
• Wrong context/host. The client targets a socket whose daemon is not running, or DOCKER_HOST points at a dead endpoint.

Diagnostic Workflow

Check the daemon service state and read why it failed:

systemctl status docker
journalctl -u docker --since '10 min ago' --no-pager

Start it if it is down:

sudo systemctl start docker

Inspect the socket file and its ownership/permissions:

ls -l /var/run/docker.sock

Confirm your user can reach it without sudo — membership in the docker group matters:

groups

If the daemon refuses to start, a malformed config is the usual cause. Validate /etc/docker/daemon.json (it must be valid JSON):

# /etc/docker/daemon.json — must be valid JSON, e.g.
# {
#   "log-driver": "json-file",
#   "log-opts": { "max-size": "10m", "max-file": "3" }
# }

Once the daemon is up, prove connectivity:

docker ps
docker compose version

Example Root Cause Analysis

An engineer edited /etc/docker/daemon.json to add log rotation and restarted Docker. Afterward, every command returned dial unix /var/run/docker.sock: connect: connection refused. ls -l /var/run/docker.sock showed the socket file was present, which ruled out the “missing socket” variant — something was preventing the daemon itself from running.

systemctl status docker reported the service in a failed state, and journalctl -u docker showed unable to configure the Docker daemon with file /etc/docker/daemon.json: invalid character — a trailing comma had made the JSON invalid. Because dockerd aborts on a bad config, it never bound the socket, so the client’s connection was refused.

The fix was to correct the JSON (remove the trailing comma), then sudo systemctl restart docker. systemctl status docker returned active (running), docker ps connected, and normal operations resumed. The lesson: connection refused with an existing socket almost always means the daemon crashed on startup — read journalctl -u docker before anything else.

Prevention Best Practices

• Enable Docker at boot: sudo systemctl enable --now docker so a reboot brings the daemon back automatically.
• Validate daemon.json before restarting. Run it through a JSON linter; a single syntax error stops the daemon from starting.
• Read journalctl -u docker first on any connection failure — it names the real reason the daemon is down.
• Add users to the docker group (or use rootless mode) so socket permissions do not masquerade as connectivity errors.
• In CI, wait for readiness. Poll docker ps until it succeeds before running builds against a Docker-in-Docker daemon. See the Docker stack guides.

Quick Command Reference

# Is the daemon up, and why did it fail?
systemctl status docker
journalctl -u docker --since '10 min ago' --no-pager

# Start it
sudo systemctl start docker

# Socket presence and permissions
ls -l /var/run/docker.sock
groups

# Prove connectivity
docker ps

Conclusion

dial unix /var/run/docker.sock: connect: connection refused means the socket exists but the Docker daemon is not accepting connections — it is stopped or crashed on startup. Check systemctl status docker, read journalctl -u docker for the real cause (often a bad daemon.json), start the service, and confirm with docker ps. Enabling Docker at boot and validating config before restarts keeps the daemon — and your socket — reliably available.