Docker 'Cannot Connect to Daemon' Error: How to Fix It on Linux, macOS & WSL2

Docker · Troubleshooting · Setup

Docker "Cannot Connect to the Daemon" Error: How to Fix It on Linux, macOS, and WSL2

You typed a docker command, got a wall of red text about a daemon that isn't running, and Docker Desktop's icon looks totally fine. Here's what's really going on underneath.

This is probably the single most common Docker error there is, and it shows up for wildly different reasons depending on your OS. On Linux it's usually a permissions problem. On macOS it's usually Docker Desktop not actually finished starting, or a stale socket reference. On WSL2 it's almost always an integration setting that got flipped off somewhere. Same error message, three completely different root causes — which is exactly why generic "restart Docker" advice only fixes it about a third of the time.

I've walked new hires through this exact error more times than I can count, usually on their first day setting up a project locally. The instinctive response is always to reinstall Docker entirely. Don't. In four years of doing this, I don't think I've ever seen a reinstall actually be the fix — it's always something smaller and more specific than that.

Level: Beginner–Intermediate Read time: ~9 min Last Updated: September 2026 Covers: Linux, macOS, WSL2

What This Error Actually Means

The Docker CLI (docker) isn't the thing doing any of the actual container work. It's a client that talks to a background process called the Docker daemon (dockerd) over a socket — usually a Unix socket at /var/run/docker.sock on Linux and macOS, or a named pipe on Windows. When you run docker ps and get "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?", the CLI is telling you, correctly, that it tried to reach that socket and got nothing back.

There are really only three reasons that happens: the daemon process genuinely isn't running, the daemon is running but your user doesn't have permission to talk to its socket, or the CLI is pointed at the wrong socket entirely because of an environment variable or context misconfiguration. Everything below maps to one of those three.

docker CLI command run

→

Tries to reach docker.sock

→

Daemon down / no permission / wrong socket

→

"Cannot connect" error

Fix It by Operating System

Linux

Usually a socket permissions issue, or the daemon service isn't actually started.

macOS

Almost always Docker Desktop still starting up, crashed silently, or a stale socket symlink.

WSL2

Nearly always the WSL integration toggle for your specific distro got turned off.

Linux: Check the Service, Then Check Permissions

Start by confirming the daemon is actually running as a systemd service. This sounds too basic to be the answer, but on fresh VM setups or after a system update, dockerd genuinely just isn't started yet.

# Is the daemon actually running? sudo systemctl status docker # If it's inactive/dead, start it sudo systemctl start docker # Make sure it starts on boot going forward sudo systemctl enable docker

If the service is active but you're still getting the connection error, it's almost certainly permissions. By default, docker.sock is owned by root and the docker group, and if your user isn't in that group, every command needs sudo or it fails with exactly this error.

# Check current permissions on the socket ls -l /var/run/docker.sock # Typically: srw-rw---- 1 root docker # Add your user to the docker group sudo usermod -aG docker $USER # Log out and back in, or run this to refresh group membership in the current shell newgrp docker

Common mistake: people run usermod -aG docker $USER and immediately try another docker command in the same terminal, and it still fails. Group membership changes don't apply to already-open shell sessions — you need a new login session, not just the same terminal window.

macOS: It's Probably Docker Desktop, Not the CLI

On macOS, dockerd runs inside the Docker Desktop VM, not as a native background service. If Docker Desktop hasn't fully finished starting — and it takes longer than people expect, especially right after a system reboot — every CLI command will throw this error even though the whale icon in your menu bar looks like it's running.

# Check whether the daemon is actually reachable yet docker info # If Docker Desktop app isn't open at all, launch it open -a Docker # Give it 20–30 seconds after the whale icon stops animating, then retry

If Docker Desktop looks "running" in the menu bar but commands still fail after waiting, the app has likely crashed silently or the socket symlink got orphaned. Quitting fully and relaunching resolves this more often than any other single fix on macOS.

Faster check: click the Docker Desktop menu bar icon directly — if it shows a red or yellow status dot instead of the normal state, it'll usually tell you exactly what's wrong (VM not started, disk image issue, etc.) instead of you having to guess from the CLI error alone.

WSL2: Check the Distro Integration Setting

This one's specific to Windows and catches people constantly. Docker Desktop on Windows runs its daemon inside a dedicated WSL2 instance, and it only exposes that daemon to your other WSL distros (Ubuntu, Debian, whatever you're using) if integration is explicitly enabled for that specific distro. Install a second distro, or reset an existing one, and that toggle often reverts to off.

# From inside your WSL distro, check if the daemon is reachable at all docker info # If it isn't, this is almost always the fix: # Docker Desktop (Windows) → Settings → Resources → WSL Integration # → Enable integration with your specific distro → Apply & Restart

Also worth checking: which WSL version your distro is actually running on. Docker Desktop's WSL2 backend won't work correctly against a distro still running WSL1.

# List distros and their WSL version wsl -l -v # Convert a distro to WSL2 if it's showing version 1 wsl --set-version Ubuntu 2

Cross-Platform Fixes Worth Checking Regardless of OS

Confirm the CLI Is Pointed at the Right Socket

If you, or a tool you installed, ever set a DOCKER_HOST environment variable — for a remote Docker context, a VM, whatever — and forgot to unset it, your CLI will try to reach that address instead of your local daemon. This produces the exact same error message and is easy to overlook because it's invisible unless you specifically check for it.

# Check if DOCKER_HOST is set to something unexpected echo $DOCKER_HOST # Unset it to fall back to the default local socket unset DOCKER_HOST # Check which context the CLI is actually using docker context ls docker context use default

Rootless Docker Has a Different Socket Path

If you're running rootless Docker (increasingly common on shared or security-conscious Linux setups), the socket isn't at /var/run/docker.sock at all — it's typically at /run/user/<uid>/docker.sock. Following standard "check the socket permissions" advice against the wrong path will send you in circles.

# Point the CLI at the rootless socket explicitly export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock # Confirm the rootless daemon service is active systemctl --user status docker

Quick Reference: Symptom to Likely Cause

Symptom	Most likely cause	Fix
Works with sudo, fails without it (Linux)	User not in docker group	usermod -aG docker $USER, then new login session
Fails right after reboot (macOS)	Docker Desktop VM still initializing	Wait 20–30s, or relaunch the app
Fails only in a specific WSL distro	WSL integration not enabled for that distro	Enable it in Docker Desktop → Resources → WSL Integration
Fails after using a remote Docker context	Stale DOCKER_HOST variable	unset DOCKER_HOST, verify with docker context ls
Fails specifically under rootless install	Wrong socket path assumed	Point DOCKER_HOST at the user-scoped socket

Mistakes That Waste Time on This Error

• Reinstalling Docker entirely as a first step — it almost never fixes a permissions or state issue, and it costs you the most time of any option on this list.
• Restarting the whole machine when restarting just the Docker Desktop app (macOS) or the docker service (Linux) would have been enough.
• Not checking docker context ls after using Docker Desktop's Kubernetes or a cloud dev environment integration — those sometimes silently switch your active context.
• On WSL2, editing the daemon config inside the WSL distro directly instead of through Docker Desktop's Windows-side settings — the WSL2 backend's actual daemon config lives in the Docker Desktop VM, not in your distro's filesystem.
• Assuming a green/running Docker Desktop icon means the daemon is actually reachable — it can lag behind the real state by several seconds, especially right after startup.

My honest take: if you're hitting this error repeatedly on the same machine, it's worth spending ten minutes finding the actual cause rather than developing a habit of just restarting Docker Desktop every morning. That habit costs more cumulative time over a year than the one-time fix would.

PTL

Published by Programming Tech Lab

Written and verified by full-stack and Linux systems engineers at Programming Tech Lab, covering container diagnostics, local development environments, and cloud infrastructure setup.

Frequently Asked Questions

Do I need to restart my computer to fix this error?

Almost never. Restarting the Docker daemon or the Docker Desktop app resolves the vast majority of cases without needing a full system restart.

Why does sudo docker ps work but docker ps doesn't?

This is a Linux permissions issue — your user account isn't part of the docker group that has access to the daemon's socket. Adding yourself to that group via sudo usermod -aG docker $USER and starting a new login session resolves it.

I enabled WSL integration but it's still not working — what else could it be?

Check that the specific distro is running WSL2, not WSL1, using wsl -l -v. Docker Desktop's WSL2 backend won't connect properly to a distro still on WSL1.

Is it safe to just delete and recreate docker.sock on Linux?

Generally no — that socket is created and managed by the daemon itself when it starts. Manually deleting it doesn't fix the underlying issue and can leave things in a confusing state; restarting the daemon service is the correct way to get a fresh socket.

Why did this error suddenly start happening after it worked fine for months?

Common triggers are a system or Docker Desktop update resetting settings, a new WSL distro install reverting integration toggles, or an environment variable like DOCKER_HOST getting set by another tool or shell profile change.

Does this error mean my containers or images are lost?

No. This is purely a connection issue between the CLI and the daemon — your images, containers, and volumes are untouched and will be visible again as soon as the connection is restored.

Can antivirus or firewall software cause this error?

Yes, particularly on Windows and macOS, where security software can block the daemon's socket or named pipe. If none of the OS-specific fixes work, temporarily checking whether security software is interfering is a reasonable next step.

Summary

The error text is identical across every OS, but the fix genuinely isn't — that mismatch is why generic troubleshooting advice fails so often here. On Linux, it's permissions or a stopped service nine times out of ten. On macOS, it's Docker Desktop not being fully up yet. On WSL2, it's the integration toggle for your specific distro. Check what your OS does differently before reaching for a full reinstall — you will almost always find it faster than you expect.