Cannot Connect to the Docker Daemon at unix:///var/run/docker.sock: Complete Fix Guide

If you run a Docker command and get slapped with this line:

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

you are not alone. This is one of the most searched Docker errors on the internet, and it shows up for developers on Linux servers, Mac laptops, Windows machines, CI pipelines, and inside WSL2 setups. The good news is that the fix is almost always simple once you know what is actually broken. The error is not a mystery. It is Docker telling you, in plain language, that the command line client could not reach the background service that actually runs your containers.

In this guide we will break down exactly what this error means, why it happens on Linux, macOS, Windows, WSL2, and inside CI/CD pipelines, and we will walk through the fixes for every scenario, including the sneaky permission issue that looks identical to a stopped daemon but needs a completely different fix. By the end you will know how to diagnose this in under a minute and apply the correct fix instead of guessing.

What “Cannot Connect to the Docker Daemon at unix:///var/run/docker.sock” Actually Means

Docker is really two things wearing one name. There is the docker command you type into your terminal, and there is dockerd, the Docker daemon, which is the background service that actually builds images, starts containers, manages networks, and talks to the Linux kernel. The CLI does not do any of the heavy lifting itself. It is a thin client that sends instructions to dockerd over an API.

On Linux and macOS, that communication normally happens over a Unix socket located at /var/run/docker.sock. Think of the socket as a phone line between the CLI and the daemon. When you type docker ps or docker run, the CLI dials that line. If nobody picks up, you get the “cannot connect to the Docker daemon” error.

There are really only three root causes behind this message, no matter which operating system you are on:

1. The Docker daemon itself is not running, so there is nothing listening on the socket.
2. The daemon is running, but your current user does not have permission to read or write to the socket file.
3. Your Docker client is pointed at the wrong place, either through a misconfigured Docker context or a stale DOCKER_HOST environment variable.

Everything in this guide maps back to one of those three causes. Once you identify which one you are dealing with, the fix takes under a minute.

Quick Diagnostic: Figure Out Which of the Three Causes You Have

Before jumping into fixes, run these four commands. They take a few seconds and will tell you exactly what is wrong.

systemctl status docker

Tells you if the daemon service is active, inactive, or failed. This is your first and most important check on any Linux system running systemd.

ls -l /var/run/docker.sock

Shows you whether the socket file exists at all and which group owns it. If the file is missing, the daemon almost certainly is not running. If it exists but your user is not in the owning group, you are looking at a permissions problem.

echo $DOCKER_HOST

If this prints anything at all, especially a remote address or a typo’d path, your client may be trying to connect somewhere other than the local socket. An empty result is what you want here.

docker context ls

Shows which context is currently active. If someone (or some install script) switched your active context away from the default, your commands could be silently pointed at a dead endpoint.

Run through those four checks first. They will point you directly at one of the sections below instead of making you try every fix in random order.

Fixing “Cannot Connect to the Docker Daemon” on Linux

Linux is the most common place to see this error because Docker Engine runs natively as a systemd service rather than inside a virtual machine. Here is the order of operations.

Step 1: Check if the Docker service is actually running

sudo systemctl status docker

If the output shows inactive (dead) or failed, the daemon simply is not running. Start it with:

sudo systemctl start docker

To make sure it survives a reboot, enable it as well:

sudo systemctl enable docker

If systemctl status docker shows a failed state with an actual error in the logs, dig deeper with:

sudo journalctl -u docker.service --no-pager -n 50

This prints the last 50 log lines from the daemon itself, which usually names the real problem, such as a corrupted storage driver, a port conflict, or a bad daemon.json configuration file.

Step 2: Fix a permission denied error on the socket

If your terminal shows permission denied while trying to connect to the Docker daemon socket instead of the “cannot connect” message, that is a different animal entirely. The daemon is up and listening, but your Linux user account is not authorized to open the socket file, which is normally owned by the docker group.

Two ways to solve it:

Option A, the correct long-term fix: add your user to the docker group so you never need sudo for Docker commands again.

sudo usermod -aG docker $USER

After running this, log out and log back in, or run newgrp docker in your current shell, since group membership does not apply retroactively to an already open session.

Option B, the quick workaround: prefix every Docker command with sudo. This works immediately but means typing sudo forever, so treat it as a temporary patch, not a real fix.

Step 3: Check for a stale or corrupted socket file

Occasionally the socket file exists on disk but is orphaned, meaning the process that used to own it crashed without cleaning up. Restarting the daemon service usually clears this automatically:

sudo systemctl restart docker

If that does not help, manually remove the stale file (only do this while the daemon is stopped) and then start the service fresh:

sudo systemctl stop docker
sudo rm -f /var/run/docker.sock
sudo systemctl start docker

Step 4: Confirm you are not on a rootless install

If you deliberately installed Docker in rootless mode, your socket will not live at /var/run/docker.sock at all. It typically lives under /run/user/<uid>/docker.sock, and you will need to export DOCKER_HOST accordingly, or make sure the rootless daemon script actually started. Running standard root-mode Docker commands against a rootless install is a common source of confusion that looks exactly like this error but has a different underlying cause.

Fixing This Error on macOS

macOS does not run Linux containers natively, so Docker Desktop for Mac spins up a lightweight Linux virtual machine in the background and forwards /var/run/docker.sock to it. That extra layer of abstraction is exactly why Mac users hit this error a little differently than Linux users.

Step 1: Confirm Docker Desktop is actually open

This sounds obvious, but it is the single most common cause on macOS. The Docker CLI is only a client. If the Docker Desktop app is not open and its whale icon is not present in the menu bar, there is no daemon running anywhere for the CLI to reach, no matter how correctly your terminal is configured.

Open Docker Desktop from Spotlight or Applications, and wait for the whale icon in the menu bar to stop animating, which signals that the internal VM and daemon have finished booting.

Step 2: Restart Docker Desktop cleanly

If Docker Desktop is open but commands still fail, quit it fully from the menu bar icon (not just closing the window) and reopen it. This forces the internal virtual machine to reboot along with the daemon process.

Step 3: Check for socket symlink issues

Docker Desktop on macOS creates a symlink from /var/run/docker.sock to a socket exposed by its internal VM. If a previous manual Docker Engine installation, a Colima setup, or another tool like Podman also tries to claim that same socket path, you get a conflict. Verify what the symlink currently points to:

ls -l /var/run/docker.sock

If it points to a path unrelated to Docker Desktop’s actual VM socket, quit any competing container tool (Colima, Podman machine, Rancher Desktop) and relaunch Docker Desktop so it can reclaim the socket.

Step 4: Reset Docker Desktop as a last resort

If none of the above works, Docker Desktop’s Troubleshoot menu (the bug icon in the top bar) includes a “Reset to factory defaults” option. This wipes local containers and images but reliably clears any deep daemon state corruption.

Fixing This Error on Windows and WSL2

Windows users see two flavors of this problem depending on whether they are using Docker Desktop’s Windows backend or running Docker inside WSL2 directly.

If you are using Docker Desktop on Windows

Make sure Docker Desktop is actually running, the same first check as macOS. Then confirm which backend it is using. In Docker Desktop settings, under General, check whether “Use the WSL 2 based engine” is enabled. If it is enabled but your WSL2 distribution is not integrated, your terminal inside that distro will never see the daemon.

Go to Settings, Resources, WSL Integration, and make sure the toggle is switched on for the specific Linux distribution you are working in (Ubuntu, Debian, etc.). Apply and restart Docker Desktop after changing this.

If you installed Docker Engine directly inside WSL2

Some developers skip Docker Desktop entirely and install Docker Engine straight into their WSL2 distribution using the standard Linux instructions. In that case, this becomes a Linux problem exactly as described earlier in this guide, and the fix is the same: check systemctl status docker (or service docker status if your WSL2 distro does not run systemd by default) and start the daemon manually if needed:

sudo service docker start

Common Windows-specific trap: virtualization disabled in BIOS

If Docker Desktop refuses to start its backend at all and throws errors about WSL2 or Hyper-V, the underlying cause is often virtualization being disabled in your machine’s BIOS/UEFI settings, or the “Virtual Machine Platform” and “Windows Subsystem for Linux” optional Windows features not being enabled. Check these in PowerShell (run as Administrator):

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Restart the machine after enabling these features.

Fixing This Error Inside CI/CD Pipelines

This error also shows up frequently in continuous integration environments like GitHub Actions, GitLab CI, Jenkins, and older Travis CI setups, and the fix here is different from a local machine because there is no interactive session to “just start Docker Desktop” in.

Make sure the runner actually has Docker available

Many CI runners are plain virtual machines with no daemon pre-installed. If your pipeline calls docker build without first ensuring a daemon exists, you will get exactly this error. Most managed CI providers document a specific way to enable Docker support, such as GitHub Actions’ hosted runners which include Docker by default, or GitLab’s docker:dind (Docker in Docker) service that must be explicitly declared in your .gitlab-ci.yml.

Use Docker in Docker (dind) correctly when containers build containers

If your pipeline itself runs inside a container and that container needs to build or run other containers, you cannot simply install the Docker CLI inside it and expect a daemon to appear. You need either:

• A sidecar docker:dind service container, with your job configured to talk to it via DOCKER_HOST=tcp://docker:2375, or
• The host’s Docker socket mounted into your job container with -v /var/run/docker.sock:/var/run/docker.sock, which lets your job container talk to the host’s actual daemon instead of running a nested one.

Mixing these two approaches, or forgetting to set DOCKER_HOST when using dind, is the most common reason this error appears specifically inside pipeline logs rather than on a developer’s own laptop.

Check runner permissions in self-hosted CI

If you run your own self-hosted runners (a common setup for teams handling sensitive client codebases), the runner’s service account needs to be in the docker group on the host, exactly as described in the Linux permissions fix above. A freshly provisioned runner user that was never added to that group will throw a permission error that gets misread as “the daemon must be down” when it is really an access problem.

How Docker Contexts Cause This Error Without You Realizing It

One of the most overlooked causes of this error is the Docker context system, a feature that lets one CLI installation talk to multiple Docker endpoints, including remote servers. If you or a script you ran ever created or switched to a custom context, your local docker command may be quietly trying to reach a server that no longer exists, rather than your local socket at all.

Check your current context:

docker context ls

The context marked with an asterisk is active. If it is anything other than default and you did not intentionally set up a remote Docker host, switch back:

docker context use default

This single command resolves a surprising number of “cannot connect” reports where the daemon was actually running perfectly fine the whole time, but the CLI had been pointed somewhere else entirely, often by a Docker Compose plugin, a cloud provider’s setup script, or an IDE’s Docker integration silently registering its own context.

Understanding daemon.json Misconfiguration Errors

Sometimes the daemon fails to start at all because of a syntax error or an invalid setting inside its configuration file, typically located at /etc/docker/daemon.json on Linux. A single misplaced comma or an unsupported key in this file will cause dockerd to refuse to start, which then produces the exact same “cannot connect” symptom on the client side, since there is genuinely nothing listening on the socket.

Validate the file’s JSON syntax:

cat /etc/docker/daemon.json
python3 -m json.tool /etc/docker/daemon.json

If the second command throws a parsing error, that pinpoints the exact line breaking your configuration. Common culprits include trailing commas after the last key, mismatched quote types, or duplicate keys left over from copy-pasting configuration snippets from different tutorials. Fix the syntax, save the file, and restart the daemon:

sudo systemctl restart docker

If you are not sure whether daemon.json is even the problem, temporarily rename it and try starting Docker with defaults:

sudo mv /etc/docker/daemon.json /etc/docker/daemon.json.bak
sudo systemctl restart docker

If the daemon starts cleanly without the file, you know the configuration itself was the root cause, and you can rebuild it setting by setting rather than restoring the broken version wholesale.

Docker Compose and This Error

Teams running docker compose up or docker-compose up hit this exact same underlying error, just wrapped in Compose’s own output formatting. Compose is not a separate daemon. It is a CLI tool that also talks to the same dockerd over the same socket, so every fix in this guide applies identically whether the failing command was docker or docker compose. If Compose specifically throws a connection error while plain docker ps works fine, double check that you are not running an old standalone docker-compose binary that was configured with its own separate DOCKER_HOST environment variable pointing somewhere stale.

Error Message Variations You Might See Instead

Docker’s exact wording has changed slightly across CLI versions and platforms, and recognizing these variants saves time, since they all trace back to the same three root causes covered earlier in this guide.

Message variant	Typical platform	Root cause
Cannot connect to the Docker daemon at unix:///var/run/docker.sock	Linux, macOS	Daemon not running, or wrong context
failed to connect to the docker API at unix:///var/run/docker.sock, no such file or directory	Newer Docker CLI, Linux	Daemon not running, socket file absent
permission denied while trying to connect to the Docker daemon socket	Linux	User not in the docker group
error during connect… open //./pipe/docker_engine: The system cannot find the file specified	Windows	Docker Desktop not running or named pipe unavailable
Cannot connect to the Docker daemon at tcp://localhost:2375	Remote or misconfigured DOCKER_HOST	Wrong or unreachable endpoint configured

Recognizing which row your exact error matches tells you immediately whether you are dealing with a stopped daemon, a permissions gap, or a misdirected client, which cuts your troubleshooting time down significantly compared to trying every fix in random order.

A Fast Checklist You Can Run Through Every Time

When this error interrupts your workflow, work down this list in order rather than guessing:

1. Is Docker Desktop or the Docker service actually open and fully started, not still booting.
2. Does systemctl status docker (Linux/WSL2) show active, or does the Docker Desktop whale icon look idle (Mac/Windows).
3. Does ls -l /var/run/docker.sock show the socket file exists and is owned by a group you belong to.
4. Is DOCKER_HOST set to something unexpected, and does docker context ls show the context you think it does.
5. If you are on CI, does your pipeline configuration actually provision a daemon (dind service, hosted runner default, or a mounted host socket) rather than assuming one exists.

Working through these five checks in order resolves the overwhelming majority of cases without needing a reinstall.

When to Stop Troubleshooting Alone and Bring in Help

Most instances of this error are quick fixes once you know which of the three root causes you are dealing with. But there are situations where this error is a symptom of something bigger: a production server where the Docker daemon keeps crashing under load, a CI pipeline that intermittently fails for reasons that are hard to reproduce locally, or a client-facing WordPress and application stack where containerized services underpin the site and any downtime is directly costing the business money.

If your team is spending hours chasing daemon errors instead of shipping features, or if your infrastructure has grown past the point where one engineer troubleshooting sockets manually is a good use of time, a proper technical consultation can get to the root cause faster and set up monitoring so these failures get caught before they become client-visible outages.

The same logic applies if this error keeps recurring on a server that also hosts a live website or application. A single Docker daemon crash on a production host can take down containerized services silently, which is exactly the kind of issue covered under ongoing WordPress bug fixing and troubleshooting support, where recurring backend errors get diagnosed and resolved as part of an ongoing relationship rather than a one-off panic search.

And if your development or deployment workflow relies on Docker as part of a larger custom build, whether that is a bespoke WordPress environment or a fully custom web application, it is worth having that pipeline reviewed by a team that builds and maintains custom website development as a core service, so daemon and container issues get engineered out of the deployment process rather than firefought every time they appear.

Frequently Asked Questions

Does restarting my computer fix “cannot connect to the Docker daemon”? Sometimes, because a restart forces the Docker service or Docker Desktop application to boot again from a clean state. However, a restart does not fix a permissions issue, since your user’s group membership is unrelated to whether the machine has been rebooted. If a reboot does not help, check the permissions and DOCKER_HOST causes described above.

Why does sudo docker ps work but docker ps does not? This is the classic sign of a permissions issue rather than a stopped daemon. Your user account is not in the docker group, so only the root user (via sudo) can talk to the socket. Add your user to the docker group as shown earlier and this gap disappears.

I reinstalled Docker Desktop and I’m still getting this error. What now? Check whether another tool is competing for the socket path, such as Colima, Podman Desktop, or Rancher Desktop. Only one of these should be actively running and owning /var/run/docker.sock at a time. Quit the others fully before relaunching Docker Desktop.

Is this error the same as “Cannot connect to the Docker daemon at tcp://localhost:2375”? Conceptually yes, the CLI still cannot reach the daemon, but the transport is different. A tcp:// address instead of a unix:// socket path means your Docker client is configured to reach the daemon over the network rather than a local file, which usually points to a misconfigured DOCKER_HOST variable or a remote Docker context that is no longer reachable.

Can antivirus or firewall software cause this error? Yes, on Windows in particular, security software has been known to block the named pipe or virtual network interface Docker Desktop relies on. If none of the standard fixes work and you are on a locked-down corporate machine, check with your IT team about whether Docker Desktop’s processes are allow-listed.

Final Thoughts

“Cannot connect to the Docker daemon at unix:///var/run/docker.sock” looks alarming the first time you see it, but it almost never means your containers, images, or data are damaged. It means the Docker CLI tried to have a conversation with a daemon that either is not running, is running but off limits to your user, or is being reached at the wrong address entirely. Work through the diagnostic checklist, match your symptom to one of the three root causes, and apply the matching fix for your operating system or CI environment.

If Docker keeps breaking on the same production or client server, that is usually a sign the underlying infrastructure needs a second look rather than another one-off restart, and that is exactly the kind of recurring technical problem a dedicated support relationship is built to catch early.