Diagnose Docker permission denied errors on Linux

A Docker permission error can come from the daemon socket, a bind-mounted directory, the build context, or the application itself. Read the failing path and operation before changing permissions. Adding a user to the docker group addresses one common rootful Engine setup, not every error containing “permission denied.”

Check the endpoint and socket

docker context show
id
ls -l /var/run/docker.sock
docker version

The socket path above is common for rootful Linux Engine. Rootless installations and other contexts may use a different path. A missing socket or an unavailable daemon needs a different investigation from a denied connection.

In a typical rootful installation, the socket is owned by root and the docker group, with group read/write permission. Confirm your installation rather than assuming its owner and mode.

Grant a trusted user group access

On a Linux system using this model, create the group only if it is absent, then add the intended account:

getent group docker || sudo groupadd docker
sudo usermod -aG docker "$USER"

Log out and back in so the new session receives the supplementary group. newgrp docker starts a shell with an updated group context and can help for the current terminal. Verify with id and docker info; docker run --rm hello-world additionally tests image availability and container execution, so network failures there do not necessarily mean permissions remain wrong.

Access to a rootful Docker daemon provides powerful host control. Do not grant the group to untrusted users or make the socket world-writable. An authorized sudo docker workflow or a correctly configured rootless engine may fit better.

Distinguish filesystem and security-policy failures

On SELinux hosts, :z is for shared labeling and :Z for private labeling in applicable bind-mount configurations. Relabel only the intended data path; indiscriminately relabeling system directories can break the host. The same group name inside and outside a container does not guarantee matching numeric IDs.

FAQ

Why does a service still fail after my terminal works?

A long-running CI agent or service may retain its old credentials and use another account or context. Restart it under the intended account and configure any supplementary group deliberately. Changing its primary group blindly is not a universal repair.

What if ~/.docker became root-owned?

This can happen after commands run with inappropriate home-directory ownership. Follow Docker's post-installation guidance to repair only the affected user configuration path after verifying it, rather than recursively changing unrelated files.

Does root inside a container bypass everything?

No. Read-only mounts, user namespaces, SELinux, and daemon-side policies can still apply. Identify the actual boundary being enforced.

See Linux post-installation, rootless mode, and bind mounts.