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.
On this page
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".
0. Rules of engagement
- Do not run every
dockercommand withsudoas the fix. It works around a permission problem without solving it, and files created that way end up owned by root. - 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. - 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| Message | Cause | Go to |
|---|---|---|
Cannot connect to the Docker daemon ... Is the docker daemon running? | dockerd is stopped or failed | Section 2 |
permission denied ... unix:///var/run/docker.sock | Your user is not allowed to use the socket | Section 3 |
failed to connect to the docker API at a path or host you did not expect | DOCKER_HOST or the Docker context points elsewhere | Section 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-pagerIf 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 dockerIf your user is not in the docker group, there are two safe options:
- Use
sudo dockerfor the occasional command on a server you administer. - 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 USERGroup 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_HOSTin a shell profile or CI variable (unset DOCKER_HOSTfor 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_DIRinstead 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-worldhello-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 adaemon.jsonchange 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.jsonin configuration management and validate it withdockerd --validatebefore restarting. - Review the
dockergroup like you review sudo access.
References
Official reference
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.