Back to blog

How to Fix Docker Volume Permission Denied Errors: User and Group ID Mapping

Mounting local directories into containers using Docker Bind Mounts (e.g., -v /host/path:/container/path) is a standard workflow for local development and database storage. It allows files to update dynamically without rebuilding images.

However, when a containerized database (like PostgreSQL) or node application attempts to read or write to the mounted volume, it frequently crashes with: "Permission denied".

This error occurs because of a mismatch in security designs: while Docker abstracts the operating system, file system permissions are governed by the host kernel's numeric User and Group IDs (UID/GID).

In this guide, we will analyze why volume permissions fail, explain UID/GID translation between hosts and containers, and implement three strategies to fix it.

The Core Cause: UID and GID Mismatches

Linux manages file permissions using numeric identifiers: UID (User ID) and GID (Group ID). The text usernames you see in your shell (like root or ubuntu) are just user-friendly wrappers mapping to these numbers.

When you mount a folder from your host into a container:

  1. The folder on the host is owned by a specific host UID (e.g., your logged-in user, which is typically UID 1000 on Ubuntu).
  2. Inside the container, the application process runs under a specific container user profile. For example, official Node.js images run under the node user (UID 1000), but official PostgreSQL images run under the postgres user (UID 999).
  3. If the container process UID (e.g., 999) does not match the host folder owner UID (e.g., 1000), the Linux kernel blocks write access, causing the "Permission denied" crash.

Solution 1: Match the Host User at Runtime (Recommended)

The most secure way to resolve this issue without altering folder ownership is to instruct Docker to execute the container processes using your active host user's UID and GID.

Use the --user (or -u) flag when running your container:

# Force container to run with the host user UID and GID
docker run -u $(id -u):$(id -g) -v /host/data:/app/data my-node-image
  • $(id -u) resolves to your host user's UID (e.g., 1000).
  • $(id -g) resolves to your host user's primary GID (e.g., 1000).

By running the container as 1000:1000, the container process matches the host directory owner, granting full read/write access.

  • Warning: Some containers require root privileges during startup to configure configurations (like changing internal network files). In these cases, passing --user may crash the container boot cycle.

Solution 2: Align Host Folder Ownership with Container UID

If your container process must run under a specific non-root user (e.g., UID 999 for PostgreSQL), you must modify the owner of the host directory to match that target ID.

Step 1: Identify the Container User ID

Inspect your container configuration or check your error stack to isolate the target UID. For example, if Postgres reports permission errors, it is looking for UID 999.

Step 2: Change Ownership on the Host

Change the folder owner on your host machine to match the container's expectations:

# Change owner of host directory to UID 999
sudo chown -R 999:999 /host/data

Once the owner is updated on the host, the container process will have write permissions natively.

Solution 3: Resolve SELinux Label Restrictions (:z or :Z)

If you are running RedHat-based Linux distributions (like CentOS, RHEL, or Fedora), the operating system utilizes SELinux (Security-Enhanced Linux) to restrict access between containers and host assets.

Even if UIDs match, SELinux will block the connection if the host directory lacks the correct security label.

To resolve this, append the :z or :Z flag to your volume mount argument:

# Append :z to flag directory as a shared container volume
docker run -v /host/data:/app/data:z my-app-image
  • :z flag: Tells Docker that the volume is shared between multiple containers, updating the SELinux label to svirt_sandbox_file_t:s0.
  • :Z flag: Tells Docker that the volume is private and dedicated to this single container, updating the label to a unique container-specific security context.

Conclusion

Docker volume permission failures are caused by discrepancies between host directory user IDs and container execution process IDs, or SELinux policies. To resolve these blocks, pass your host UID using the -u $(id -u):$(id -g) flag at launch, modify host directory ownership using chown to match container target IDs, or append :z parameters to configure SELinux security labels automatically.