Troubleshooting Docker Permission Denied Problems

Published:13 October 2021 - 5 min. read

Azure Cloud Labs: these FREE, on‑demand Azure Cloud Labs will get you into a real‑world environment and account, walking you through step‑by‑step how to best protect, secure, and recover Azure data.

Running applications with Docker as a daily routine can become a nightmare when you run into an error such as Docker permission denied while trying to connect. But don’t worry, this article will help you get back running in no time.

In this tutorial, you will learn many ways to resolve the dreaded Docker permission denied error message.

Prerequisites

This tutorial comprises hands-on demonstrations. To follow along, be sure you have the following in place:

  • The demos in this tutorial run on Ubuntu 20.04, but other Linux distributions will also work.
  • The Docker engine, with the tutorial running version 20.10.8, build 3967b7d.

Running Elevated Docker Commands

Many factors could lead to a permission denied error while connecting to Docker. One of those factors is that you may be running Docker commands without prepending the sudo command. The sudo command is what gives you elevated administrative rights along with security privileges when running commands.

Below, you can see the dreaded permission denied error while trying to run a docker command.

Running into a permission denied error
Running into a permission denied error

Launch your terminal and prepend sudo to the docker command below to run the hello-world Docker image. Since you’re running an elevated command, you’ll need to enter your password to proceed.

sudo docker run hello-world

You’ll see an output similar to that shown below that indicates that Docker is installed correctly.

Running Elevated (sudo) Docker Commands
Running Elevated (sudo) Docker Commands

Restarting the Docker Engine

If running elevated Docker commands does not fix the permission denied error, verify that your Docker Engine is running. Similar to running a docker command without the sudo command, a stopped Docker Engine triggers the permission denied error. How do you fix the error? By restarting your Docker engine.

Run the systemctl command below to confirm the Docker Engine’s status (status docker) and if it’s running.

sudo systemctl status docker

Below, you can tell the Docker Engine is running from the returned status that shows active (running).

Displaying Docker Engine status
Displaying Docker Engine status

If the Docker Engine isn’t active, run the systemctl command below to start the Docker Engine (start docker).

sudo systemctl start docker

Now, run the hello-world Docker command as you did in the “Running Elevated Docker Commands” section to verify that the error is resolved.

sudo docker run hello-world

Adding User Account to a Group with Non-Root User Access

You’ve confirmed your Docker engine is working, but you’re still getting a Docker permission denied error? If so, you need to add your user account to a group with non-root user access. Why? Because any Docker command you run on a Linux machine not in the user group triggers permission denied error.

  1. Run the groupadd command below to create a new group called docker. Enter your password to continue running the command.
sudo groupadd docker

If the docker group exists in the user group, you will see an output like the one below.

Creating a New Group Named 'docker'
Creating a New Group Named ‘docker’

2. Next, run the usermod command below where the -aG options tell the command to add your user account (programmer) to the (docker) group. This command causes your user account to have non-user access.

sudo usermod -aG docker programmer

3. Run the newgrp command below to change the current real group ID to the docker group.

Run this command each time you want to run Docker as a non-root user.

sudo newgrp docker 

4. Finally, rerun the hello-world Docker image to confirm that you no longer see the error. If, at this point, you’re still getting an error, then consider giving more access to the docker.sock file. The docker.sock file is the UNIX socket, a way to communicate process information between the user and the system, that the Docker daemon listens to as the Docker API’s entry point.

Run the chmod command below to grant all users read/write (666) access to the /var/run/docker.sock file. Now run the hello-world Docker image again to see if the error is resolved.

sudo chmod 666 /var/run/docker.sock

Editing the Docker Service Unit File

If running Docker as a non-root user is not enough to fix the error, try editing the Docker SystemD, a service control system, service unit file. The Docker service file contains sensitive parameters that may alter the behavior of the Docker daemon. You can modify the Docker unit file’s default behavior by adding an extra command to change the service default behavior.

1. Run the command below to open the Docker service unit file in your favorite text editor. For this example, the Docker service file opens in the nano text editor.

sudo nano /usr/lib/systemd/system/docker.service

2. Locate the area with the [Service] header inside the Docker service unit file, as shown below. Copy/paste the commands below to the Docker service unit file and save the changes.

Below, the SupplementaryGroups command sets the supplementary Unix groups to where the processes are executed. At the same time, the ExecStartPost command cleans up operations that are executed even if the service fails to start up correctly.

SupplementaryGroups=docker    
ExecStartPost=/bin/chmod 666 /var/run/docker.sock
Editing the Docker Service Unit File
Editing the Docker Service Unit File

3. Now, run the commands below to restart and enable the Docker service. Doing so lets you start the Docker service anew to avoid getting errors when you run Docker commands.

# Reloads all the Docker unit files and recreates the entire dependency tree.
sudo systemctl daemon-reload
# Restarts the Docker service
sudo systemctl start docker
# Enable the Docker to run on your computer.
sudo systemctl enable docker

4. Finally, rerun the hello-world Docker image and see if you still get the permission denied error.

Running Docker in Privilege Mode

Last but not least, on the list of fixing the Docker permission denied error is running Docker in privileged mode. Doing so grants a Docker container root access to the system.

Running Docker in privileged mode is risky and vulnerable to attacks from hackers. So be cautious and only run the Docker in privileged mode when you know exactly what you’re doing.

1. Run the command below to list all Docker containers in your system, and get the ID of the container you want to run.

sudo docker ls -a
Listing all Docker Containers in the System
Listing all Docker Containers in the System

2. Next, run the docker inspect command below to check if the container you want to run is already in privileged mode (--format='{{.HostConfig.Privileged}}'). Replace CONTAINER_ID below with the actual container ID that you took note of in step one.

docker inspect --format='{{.HostConfig.Privileged}}' CONTAINER_ID

If the container is in privileged mode, the command returns a true value to the console. But if the command returns a false value, as shown below, move on to the next step.

Checking if a Container is in Privileged Mode
Checking if a Container is in Privileged Mode

3. Finally, run the docker command below to run the Docker container in privileged mode (--privileged hello-world).

sudo docker run --privileged hello-world

Conclusion

Throughout this tutorial, you’ve learned many ways to solve the Docker permission denied error, from running elevated commands to running Docker in privileged mode.

Now you know how to rid of an error when building Docker-powered applications; perhaps you also want to keep your Docker images clean at all times?

Hate ads? Want to support the writer? Get many of our tutorials packaged as an ATA Guidebook.

Explore ATA Guidebooks

Looks like you're offline!