Docker "Cannot connect to the daemon" Error: A Complete 5-Cause Fix Guide

Docker "Cannot connect to the Docker daemon" Error: A 5-Minute Recovery Guide by 5 Root Causes

If you are a developer, you have probably hit this at least once—the most frustrating, dead-end error message of them all: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.

When you see it, most people assume Docker is not running, try a reboot, or waste time running sudo docker ps. But this error is not a single "Docker isn't running" problem. It is an umbrella symptom for five kinds of connection issues that occur while the client (CLI) talks to the daemon.

This post does not hand you a vague "just give it sudo" fix. It is a practical guide that lets you tell—with a single diagnostic command—whether the problem is the daemon itself, permissions, or a wrong connection path (context), and recover in five minutes.

🚨 30-Second Diagnostic Table: Narrow the Cause by Symptom Pattern

When all you see is a vague error, start with this table. Find the "symptom / extra clue" that matches your situation most closely, then run the diagnostic command. That is the fastest path.

⚙️ Cause ①: The Docker daemon itself is stopped (most common)

This is the simplest case—and the easiest to miss. The Docker service is simply not running at the OS level.

🔍 Diagnostic command (copy-paste):

systemctl status docker

💡 How to read the output: If the Active: line shows inactive (dead) or failed, that is a clear signal the daemon process is not running.

🛠️ Fix command (copy-paste):

sudo systemctl start docker
sudo systemctl enable docker  # 부팅 시 자동 시작을 원할 경우

Tip: If docker ps without sudo fails with a permission error but sudo docker ps succeeds, you are likely looking at a permissions problem (Cause ②).

🛡️ Cause ②: User permission problem (Permission Denied)

This is the most common wall on Linux. The Docker socket file (/var/run/docker.sock) is owned by the docker group, and the current user is not in that group, so access is denied.

🔍 Diagnostic command (copy-paste):

ls -l /var/run/docker.sock

💡 How to read the output: If the owning group is docker and the error message clearly includes permission denied, this case is 99% certain.

🛠️ Fix command (copy-paste):

sudo usermod -aG docker $USER
# 변경 사항을 즉시 적용하기 위해 로그아웃 후 재접속하거나, 아래 명령 실행
newgrp docker

Note: You can temporarily test with sudo docker ps, but that is only a workaround. The real fix is adding the user to the docker group.

🔗 Cause ③: Context or socket path mismatch

Docker uses the concept of a "context" so you can work across environments (local, remote servers, Docker Desktop, and so on). This error happens when that context is pointing at the wrong socket path.

🔍 Diagnostic command (copy-paste):

docker context ls
echo $DOCKER_HOST

💡 How to read the output: When you run docker context ls, the currently active context (marked with *) may not match the environment you intend to work in (for example, your local machine). Or the DOCKER_HOST environment variable may be set incorrectly.

🛠️ Fix command (copy-paste):

docker context use default
# 만약 DOCKER_HOST가 설정되어 있다면, 임시로 제거해봅니다.
unset DOCKER_HOST

In this case the daemon is healthy; the client is simply looking for a socket "over there" instead of "here."

👤 Cause ④: Socket path issues in a rootless environment

More teams run Docker in rootless mode for better security. That mode uses a per-user path (/run/user/...) instead of the system default (var/run/docker.sock).

🔍 Diagnostic command (copy-paste):

docker context ls
# rootless 관련 컨텍스트가 활성화되어 있는지 확인

💡 How to read the output: If a rootless context is active and basic commands like docker ps fail in that environment, the client may be pointing at the rootless socket while the daemon itself never started correctly.

🛠️ Fix command (copy-paste):

# 1. 환경 변수를 정확한 rootless 소켓으로 지정
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
# 2. 사용자 레벨에서 데몬 재시작 시도 (systemctl --user)
systemctl --user start docker

In this case you must manage the service at the current user session (user daemon) level, not as a system-wide service (system daemon).

💻 Cause ⑤: Docker Desktop or WSL2 integration issues (Mac/WSL2 only)

This is the most common issue when using Docker on Mac or Windows WSL2. The CLI is installed, but the actual container engine (daemon) is supposed to be driven by a GUI app (Docker Desktop). If that engine is stopped or WSL2 integration is disabled, you get this error.

🔍 Diagnostic command (copy-paste):

• Mac: Check the Docker Desktop app status bar icon
• WSL2: Run wsl -d <DistroName>, then confirm WSL Integration is enabled in Docker Desktop settings

💡 How to read the output: You cannot tell from CLI commands alone. If the GUI app is not in a 'Running' state, or if integration for that distro is off in WSL2 settings, the client has nothing to connect to.

🛠️ Fix command (copy-paste):

1. Mac: Fully quit the Docker Desktop app, then start it again.
2. WSL2: Run the following in a terminal to shut down all WSL2 VMs, then start again.
   Bash복사

   wsl --shutdown
   # 이후, WSL2 터미널을 새로 열고 docker 명령 실행

💡 Practitioner's field note: When I hit this error, the first question I ask is: "What environment am I actually working in right now?" On a local desktop, check Docker Desktop's status. In CI/CD, check systemctl status. In a container orchestration setup, inspect docker context. This error is ultimately asking where, who, and what you are pointing at.

📝 Recurrence-prevention checklist

1. Permissions: Minimize sudo usage and confirm the user account is permanently added to the docker group.
2. Environment: Before you start work, get in the habit of running docker context ls to confirm the active context is the one you intend.
3. Engine: Mac/WSL2 users should always glance at the Docker Desktop status bar to visually confirm the engine is alive.

References: official docs

The primary source for the behavior, settings, and errors covered in this post is the official documentation below. Check it for version-specific options and exact behavior.

• Docker official documentation

Frequently asked questions (FAQ)

Q. Why does sudo docker ps work when docker ps does not? A. This is a classic permissions issue. With sudo, the command runs as root, so it can reach the socket without a permission error. The real fix is adding your user account to the docker group.

Q. I ran docker context use default and still get the error. A. The problem is likely not the context setting—Docker Desktop (or Docker Engine) itself is probably not running correctly in the background. Restart that engine, or on WSL2 run wsl --shutdown to reset it.

Q. systemctl status docker shows active (running) but I still cannot connect. A. In that case it is either a socket permission problem (Cause ②), or a GUI layer such as Docker Desktop is colliding with the system service. Recheck the owning group with ls -l /var/run/docker.sock.