Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

Docker: permission denied while trying to connect to the Docker daemon socket

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

The error permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock means the Docker command-line client reached for the daemon's Unix socket and the operating system refused your account. By default that socket is open to root and to members of the docker group only. You can use sudo, join the group, or use rootless mode, but the group is not a minor convenience: Docker's own documentation warns that it grants root-level privileges.

What the error means

Docker's Linux post-installation page says the Docker daemon binds to a Unix socket, not a TCP port. By default the root user owns the socket and other users can only use it with sudo. The daemon always runs as root. When the daemon starts it creates a Unix socket accessible to members of the docker group. The dockerd reference agrees: by default a Unix domain socket is created at /var/run/docker.sock, requiring either root permission or docker group membership. The same reference lists -G, --group with the default docker, which sets the group for the Unix socket.

The wording of the message depends on the client version. In the Docker Engine client source at tags v27.5.1 and v28.5.1 the message is permission denied while trying to connect to the Docker daemon socket at followed by the daemon address; the default address in the source is unix:///var/run/docker.sock. At tag docker-v29.10.0 the same condition reads permission denied while trying to connect to the docker API at followed by the address. Search for either form.

A different failure has a different message. In the docker-v29.10.0 source, a missing socket gives failed to connect to the docker API at the address, then check if the path is correct and if the daemon is running. That one is about a stopped daemon or wrong path, not permissions.

Likely causes

Cause What you see How to confirm
Your user is not in the docker group Permission denied on every docker command except with sudo id -nG does not list docker
You were added to the group but the session is old Still denied after usermod Group membership is evaluated at login; id -nG in the current shell still lacks docker
The group does not exist, or the socket is owned by a different group Group steps appear to do nothing ls -l /var/run/docker.sock shows an owner group other than docker; getent group docker shows nothing
DOCKER_HOST points at another socket The address in the message is not the default echo "$DOCKER_HOST" prints a value
A service or CI account was never added Works for you, fails for the pipeline user id -nG run as that account
~/.docker was created by root through sudo A different error: Error loading config file ... stat /home/user/.docker/config.json: permission denied The directory is owned by root; Docker's post-install page describes this error

Prove the cause before changing anything

All of these are read-only.

1. Which groups does this account have?

id -nG

The Docker documentation uses this command to list group names. A good result includes docker.

2. Who owns the socket?

ls -l /var/run/docker.sock
getent group docker

ls -l prints a long listing, with owner and group. getent group docker prints the group entry and its members if the group exists.

3. Is a custom address in use?

echo "$DOCKER_HOST"

The Docker security page shows DOCKER_HOST=ssh://USER@HOST as a way to point the client at a remote daemon. An empty value means the client uses its default, unix:///var/run/docker.sock.

4. Is it only the config directory? If the message mentions config.json, read the owner with ls -ld ~/.docker.

Fix

First decide whether this account should control Docker at all. The Docker security page says only trusted users should be allowed to control the Docker daemon, because Docker allows a container to mount any host directory, including /, without limiting the container's rights. The post-installation page repeats the point: the docker group grants root-level privileges to the user. Anyone in that group can read or change the host's files through a container.

Option A: use sudo. Run sudo docker .... This adds a password or policy step and keeps root access under your normal sudo rules. The post-installation page notes a side effect: if you first ran Docker CLI commands with sudo and later added the user to the group, you may see the config.json permission error described above.

Option B: add the user to the group. Save the current state first:

getent group docker
id -nG USERNAME

Replace USERNAME with the account. If getent printed nothing, create the group with sudo groupadd docker; on some distributions the package creates it.

Risk: adding the user to the docker group grants the user root-level control of the host through Docker, for every process in the user's login session. Back-out: sudo gpasswd --delete USERNAME docker, and sign the user out and in again, because group membership stays in the credentials of existing processes.

Then add the user to the group:

sudo usermod -aG docker USERNAME

Then the user logs out and back in so the new membership is evaluated (on a virtual machine, a restart may be needed, per Docker's page), or runs newgrp docker in the current shell. Verify with docker run hello-world.

Option C: a password-gated shell. Docker's page describes keeping your user out of the group, setting a group password with gpasswd, and entering a Docker-enabled shell with newgrp docker. The page says this reduces ambient access but does not reduce the root-level privilege once authorised, group passwords are shared secrets without per-user accountability, and the method is not a security boundary against malicious code running as your user. It is meant for a single-user workstation.

Option D: rootless mode. Docker's rootless page says rootless mode runs the Docker daemon and containers as a non-root user, and describes the setup script dockerd-rootless-setuptool.sh install, run as a non-root user. It has its own limits and prerequisites; read that page before choosing it for a production host.

If the ~/.docker directory is the problem. Select the exact directory and record every owner and mode under it first, because the change applies recursively:

ls -ld "$HOME/.docker"
ls -lAR "$HOME/.docker"

Risk: changing the ownership and permissions of ~/.docker with the recursive option applies to everything under that directory, and the permission change adds group read, write and execute. Back-out: use the ls -lAR listing you kept to restore each entry's owner and mode with chown and chmod.

Docker's page gives two ways: remove the directory (it is recreated, but custom settings are lost), or change its ownership and permissions. Run these as the affected user:

sudo chown "$USER":"$USER" /home/"$USER"/.docker -R
sudo chmod g+rwx "$HOME/.docker" -R

If the socket's group is not docker. The daemon may have been started with a different -G, --group value, the dockerd option the reference describes as the group for the Unix socket. The dockerd reference's example daemon.json also lists a "group" key, so find where your daemon is started (a service unit or a configuration file) and change the group setting there, or return it to docker. Docker's pages do not cover hosts where the socket is created by a systemd socket unit; check that unit instead. Change the daemon's configuration deliberately. The default configuration file on Linux is /etc/docker/daemon.json, but it need not exist. If it exists, save it with a dated name first:

cp -p /etc/docker/daemon.json /etc/docker/daemon.json.2026-11-20.bak

If the file does not exist, the copy fails and there is nothing to save; in that case the back-out is to remove the new /etc/docker/daemon.json you create.

After editing, test the file with the command below, which the dockerd reference describes as validating a configuration file without starting the daemon:

dockerd --validate --config-file=/etc/docker/daemon.json

Restarting the Docker daemon is a separate Disruptive step: the Docker page on exit status 137 lists a daemon restart as an event that kills running containers. Back-out: if you saved a copy, copy /etc/docker/daemon.json.2026-11-20.bak back over /etc/docker/daemon.json; if the file did not exist before, remove the /etc/docker/daemon.json you created. Where the file is restored, run the same dockerd --validate command. Then restart the daemon.

Example (illustrative): on app01, the account deploy runs docker ps and gets permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock. id -nG shows deploy only. ls -l /var/run/docker.sock shows the group is docker, and getent group docker lists one member, ops. The owner of the server decides deploy is a trusted administrator, runs sudo usermod -aG docker deploy, and asks the user to sign out and in. id -nG now includes docker and docker ps works. The owner records the change and the back-out, sudo gpasswd --delete deploy docker, in the change ticket.

Confirm the fix

Run docker run hello-world as the user (the Docker page's own check), or docker ps. Run id -nG in the new session: it must include docker for Option B. For Option C, id -gn shows docker as the primary group inside the child shell and id -nG outside does not list it.

What to watch afterwards

  • The member list from getent group docker, checked on a schedule; every member is a root-equivalent account.
  • Service and CI accounts in that group.
  • New containers that mount host paths such as / or /etc.
  • Any change to the socket's group or mode after a Docker upgrade.

Risks and limits

The docker group is not a limited permission. Adding someone to it is the same as giving them root on that host, and group passwords or newgrp do not change that once access is granted. The message text differs between client versions, so a search that finds only one wording will miss the other. These commands have not been run or lab-tested.

Sources