---
title: "Docker API Permission Denied? 5 Fixes That Actually Work"
description: "Got permission denied while trying to connect to the Docker daemon API? Fix socket group, rootless, DOCKER_HOST, and context mismatches."
author: "Mohammad Pouya Ghourchiani"
canonical: "https://ghourchiani.ir/blog/docker-permission-denied-api-socket"
image: "https://ghourchiani.ir/og/mark-square.png"
date: "2026-11-17"
lang: "en"
generated: "2026-11-19"
---
# Docker API Permission Denied? 5 Fixes That Actually Work

> **TL;DR:** The error permission denied while trying to connect to the Docker daemon API almost always means your CLI cannot talk to the engine socket. Check group membership, newgrp/re-login, rootless vs rootful, DOCKER_HOST, and the active docker context — in that order.

## 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`.

```sh
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)

```sh
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

```sh
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.

```sh
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

```sh
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:

```sh
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:

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

## Prove it

```sh
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).

## Links

- [/blog/cve-2026-98432-docker-container-namespaces](/blog/cve-2026-98432-docker-container-namespaces) — host “fixed”, containers still lying
- [/blog/mirror-first-dx](/blog/mirror-first-dx) — when Hub/egress is the next pain after the socket works
- [/about](/about) · [/contact](/contact)
