We earn commissions when you shop through the links below, at no extra cost to you. Our guides and technical recommendations are written independently of these relationships: a commission never decides what we recommend, how we diagnose a problem or what we publish, and the content does not depend on it. Affiliate disclosure

Docker · Beginner · 10 min

Fix 'Cannot connect to the Docker daemon'

Fix "Cannot connect to the Docker daemon": start the daemon, grant access to docker.sock safely, or point DOCKER_HOST back at it.

The docker command is a client that talks to the daemon through a socket. This runbook reads the three messages Docker 29 prints, then starts the daemon, grants socket access with its real cost in mind, or points the client back at the right endpoint. Commands were run on Ubuntu 26.04 with Docker Engine 29.1.3.

See it run

A short replay of real output from commands in this guide, captured on a WSL2 Ubuntu test machine (Docker 29.1.3 with systemd, run as root; the daemon was stopped for the demo and a throwaway user was created and removed). The typing is replayed, and the host name, account and MAC addresses are redacted. Your output will differ, and a test machine is not a production server.

Text version of this demo
ops@web-01:~$ docker ps
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

ops@web-01:~$ systemctl is-active docker.service docker.socket
inactive
inactive

ops@web-01:~$ sudo systemctl start docker.service && docker version --format 'client {{.Client.Version}} server {{.Server.Version}}'
client 29.1.3 server 29.1.3

ops@web-01:~$ ls -l /var/run/docker.sock
srw-rw---- 1 root docker 0 Oct 31 00:12 /var/run/docker.sock

ops@web-01:~$ su obtest -c 'docker ps'
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

ops@web-01:~$ echo "DOCKER_HOST=${DOCKER_HOST:-unset}"; docker context ls
DOCKER_HOST=unset
NAME        DESCRIPTION                               DOCKER ENDPOINT               ERROR
default *   Current DOCKER_HOST based configuration   unix:///var/run/docker.sock   

The docker command is only a client. It sends every request to the Docker daemon (dockerd) through a socket, usually /var/run/docker.sock. When the client cannot reach that socket, every command fails before Docker does any work. There are three common reasons: the daemon is not running, your user may not open the socket, or the client is pointed at a different socket or host. The message tells you which.

Commands and output were captured on an Ubuntu 26.04 test machine with Docker Engine 29.1.3, using systemd. Docker 29 reworded two of the messages; older versions say "Docker daemon socket" where Docker 29 says "docker API".

Where the docker command fails before Docker starts any work1. docker client (reads DOCKER_HOST and the active context (section 4)) [failed to connect to the docker API at ...] Then 2. The socket (/var/run/docker.sock: your user must be allowed to open it (section 3)) [permission denied] Then 3. dockerd (the daemon must be running (section 2)) [Is the docker daemon running?].docker clientreads DOCKER_HOST and theactive context (section 4)failed to connect to thedocker API at ...The socket/var/run/docker.sock: your usermust be allowed to open it(section 3)permission denieddockerdthe daemon must be running(section 2)Is the docker daemon running?
The docker command only forwards requests. The message names the stage that failed: the client points somewhere else, your user cannot open the socket, or nothing is running behind it.

0. Rules of engagement

  1. Do not run every docker command with sudo as the fix. It works around a permission problem without solving it, and files created that way end up owned by root.
  2. Do not chmod 666 /var/run/docker.sock. Anyone who can write to that socket can control Docker, and through it the host. The permission is restricted on purpose.
  3. Read before you restart. If the daemon failed, its log says why; a restart loop hides that.

1. Read the message

# The daemon is not running (real output from the test machine)
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
# The daemon runs, but your user may not open the socket (Docker 29)
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock
# The client is pointed somewhere else, here through DOCKER_HOST (Docker 29)
failed to connect to the docker API at unix:///tmp/nope.sock; check if the path is correct and if the daemon is running: dial unix /tmp/nope.sock: connect: no such file or directory
MessageCauseGo to
Cannot connect to the Docker daemon ... Is the docker daemon running?dockerd is stopped or failedSection 2
permission denied ... unix:///var/run/docker.sockYour user is not allowed to use the socketSection 3
failed to connect to the docker API at a path or host you did not expectDOCKER_HOST or the Docker context points elsewhereSection 4

All three exit with code 1.

2. The daemon is not running

# State of the daemon and of the socket that starts it on demand
systemctl is-active docker.service docker.socket
# Real output from the test machine with both stopped
inactive
inactive
# The last lines the daemon logged: read these before you start it again
journalctl -u docker.service -n 50 --no-pager

If the log shows a clean stop (someone ran systemctl stop), start it:

# Start the daemon and check that it answers
sudo systemctl start docker.service
docker version --format 'client {{.Client.Version}} server {{.Server.Version}}'

If the log shows an error, fix that first. Common ones are a syntax error in /etc/docker/daemon.json, a full disk under /var/lib/docker, or a storage driver that does not match the filesystem. sudo dockerd --validate checks daemon.json without starting the daemon.

Socket activation. On systemd hosts, docker.socket can start the daemon on the first request. Stopping only docker.service is not enough to keep it down: systemd warns Stopping 'docker.service', but its triggering units are still active: docker.socket, and the next docker command starts the daemon again. To keep it stopped for maintenance, stop both units.

WSL and other hosts without systemd. Check ps -C dockerd. On Docker Desktop, the daemon runs inside Docker Desktop: start Docker Desktop and wait until it reports that the engine is running.

3. Permission denied on the socket

# Who may open the socket: owner root, group docker, no access for others
ls -l /var/run/docker.sock
# Real output from the test machine
srw-rw---- 1 root docker 0 Oct 31 00:12 /var/run/docker.sock
# Your groups, and the members of the docker group
id -nG
getent group docker

If your user is not in the docker group, there are two safe options:

  1. Use sudo docker for the occasional command on a server you administer.
  2. Add the user to the group when they should manage Docker:
# Give USER access to the Docker socket (log out and in again afterwards)
sudo usermod -aG docker USER

Group changes apply to new login sessions only. Until then id -nG still shows the old groups; log out and back in, or start a new shell with newgrp docker.

Know what the group means. A member of docker can start a container that mounts the host's root filesystem, so the group is equivalent to root on that host. Grant it the way you would grant sudo. Rootless Docker is the alternative when users need containers without that power.

4. The client points somewhere else

# Which endpoint the client uses: DOCKER_HOST overrides the context
echo "DOCKER_HOST=${DOCKER_HOST:-unset}"
docker context ls
# Real output from the test machine
DOCKER_HOST=unset
NAME        DESCRIPTION                               DOCKER ENDPOINT               ERROR
default *   Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
  • A leftover DOCKER_HOST in a shell profile or CI variable (unset DOCKER_HOST for the current shell, then remove it at the source).
  • A selected context for a remote host or Docker Desktop that is not running (docker context use default).
  • Rootless Docker uses a socket under $XDG_RUNTIME_DIR instead of /var/run/docker.sock.

5. Verify

# Both client and server answer, and a container can start
docker version --format 'client {{.Client.Version}} server {{.Server.Version}}'
docker run --rm hello-world

hello-world needs to pull an image; on an offline host, run docker ps instead.

6. Rollback and prevention

  • Rollback: remove a user you added by mistake with sudo gpasswd -d USER docker. Revert a daemon.json change from your backup, then restart the daemon.
  • Enable the daemon at boot where it should always run: sudo systemctl enable --now docker.service.
  • Keep daemon.json in configuration management and validate it with dockerd --validate before restarting.
  • Review the docker group like you review sudo access.

References

Official reference

docs.docker.com ↗

Technical steps are original explanations; consult the upstream documentation for version-specific details.

Behavior differs by distribution and tool version. Commands are examples for authorized systems; review output for secrets before sharing.

Found this useful?

Follow us on YouTube for video explainers, and find us on Facebook to keep up with what is new.