Blog

Docker API Permission Denied? 5 Fixes That Actually Work

Got permission denied while trying to connect to the Docker daemon API? Fix socket group, rootless, DOCKER_HOST, and context mismatches.

By Pouya GhourchianiGhourchiani

engineeringinfrastructuredeveloper-tooling

Direct answer

permission denied while trying to connect to the Docker daemon API at unix:///var/run/docker.sock means your docker CLI reached a socket and the kernel said no. It is usually not a broken install. Fix, in order: (1) user in docker group, (2) re-login or newgrp docker, (3) socket path/permissions, (4) rootless vs rootful mismatch, (5) wrong DOCKER_HOST / docker context.

Shell
docker info >/dev/null
# if that fails:
groups
ls -l /var/run/docker.sock
echo "DOCKER_HOST=${DOCKER_HOST:-<unset>}"
docker context show

The vibe 🫠

You installed Docker. Tutorial said “done”. You type docker ps and the machine replies like a bouncer:

Permission denied. Nice try.

Same energy as locking the lobby and forgetting your own keycard. The engine is often fine. Your user is the problem — or the env var you pasted three hours ago is.

Fix 1 — Join the docker group (most common on Linux)

Shell
sudo usermod -aG docker "$USER"
# then fully log out/in, or:
newgrp docker
docker ps

usermod alone is not enough. Your current shell still has the old group list. That is why half the internet says “I added myself to docker and nothing changed.”

Fix 2 — Confirm the socket, not vibes

Shell
ls -l /var/run/docker.sock
# expect something like: srw-rw---- root docker ... /var/run/docker.sock
stat /var/run/docker.sock

If the group is not docker, or mode is not group-writable for that group, dockerd / packaging is wrong — reinstall the engine package, do not chmod 777 the socket and call it security.

Fix 3 — Rootless vs rootful (two different engines)

Rootless Docker listens elsewhere (often under $XDG_RUNTIME_DIR/docker.sock). If you set up rootless but your shell still points at /var/run/docker.sock, you get permission denied on the rootful socket you are not allowed to use.

Shell
systemctl --user status docker 2>/dev/null || true
echo "DOCKER_HOST=${DOCKER_HOST:-<unset>}"
# rootless tip (when using rootless kit):
# export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock

Pick one story. Do not mix sudo dockerd with a rootless DOCKER_HOST from a blog comment.

Fix 4 — DOCKER_HOST and context lie to you

Shell
env | grep -E '^DOCKER_' || true
docker context ls
docker context show

A stale DOCKER_HOST=tcp://... or a Desktop context on a headless box will send the CLI somewhere you cannot auth. Clear it:

Shell
unset DOCKER_HOST
docker context use default
docker info

On Docker Desktop (Windows/macOS), “permission denied” often means the VM/engine is stopped — start Desktop, wait until it is healthy, then retry. The Linux socket story above is for engine-on-Linux.

Fix 5 — Snap / odd installs

If Docker came from Snap or a random script, socket paths and groups can disagree with what docker.com docs assume. Prefer the distro or Docker Inc. engine packages for servers. For a quick signal:

Shell
which docker
docker version
ps aux | grep -E '[d]ockerd'

Prove it

Shell
docker run --rm hello-world
docker compose version  # if you use compose

If docker info works and compose fails, you have a Compose install problem — not the API socket.

Checklist

  1. groups contains docker (after re-login / newgrp).
  2. /var/run/docker.sock is root:docker with group rw (rootful).
  3. Not accidentally hitting rootful socket while living in rootless land.
  4. DOCKER_HOST unset or correct; docker context is the one you think.
  5. Engine actually running (dockerd / Desktop healthy).