Tired of Docker’s infamous ‘permission denied’ errors when mounting volumes from your NAS? This guide demystifies the PUID/PGID mismatch on systems like OpenMediaVault and provides real-world fixes for apps like Immich so you can finally get things working.

That ‘Permission Denied’ Error in Docker? Let’s Talk About PUIDs, PGIDs, and Your Sanity.

I remember it like it was yesterday. 2 AM, a critical deployment pipeline is failing, and the logs are screaming ‘Permission Denied’. We were trying to write build artifacts from a Jenkins container to a mounted NFS share on our main storage server, `nas-storage-01`. The path was correct, the volume was mounted, everything on the host looked fine. But the container, blissfully unaware of our host’s user structure, was running as its own internal user, and the host kernel just saw some random user ID trying to write to a protected directory. That night, I truly learned the meaning of UID/GID hell, and it’s a lesson that sticks with you.

The “Why”: You and Your Container Aren’t the Same Person

Here’s the bit that trips everyone up. When you run a Docker container, it has its own set of users and groups inside it. A common one is a user named `node` or `appuser` with a User ID (UID) of `1000`. Meanwhile, on your host machine (like your OpenMediaVault server), you have your own user, let’s call him `dave`, who might also have a UID of `1000`.

You’d think they are the same, right? Wrong. The Linux kernel doesn’t care about names; it only cares about the numbers. When you mount a host directory like /srv/dev-disk-by-uuid-foobar/media into the container, the kernel enforces permissions based on the numerical UID and Group ID (GID) of the process running inside the container.

So, if the container process runs as UID `911` and your media files on the host are owned by `dave` (UID `1000`), the kernel says “Nope, access denied.” The container has no idea who `dave` is, and the host has no idea who the container’s user is. They’re just two different numbers trying to access the same file.

The Fixes: From Duct Tape to Solid Engineering

I’ve seen this problem “solved” in a dozen ways, but they usually fall into one of three camps. Let’s break them down, from the one that makes me cringe to the one I use on my own homelab.

1. The Quick & Dirty Fix: `chmod 777`

Let’s be honest, we’ve all done it in a moment of desperation. You’re frustrated, you just want the thing to work, so you run the command that blows the doors wide open:

# On your host machine (e.g., OMV server via SSH)
chmod -R 777 /path/to/your/immich/library

This command gives read, write, and execute permissions to everyone: the owner, the group, and any other user on the system. Does it work? Yes. Is it a good idea? Absolutely not. You’ve just removed all meaningful security from that directory. It’s a band-aid on a bullet wound.

Darian’s Take: Please, for the love of all that is secure, don’t do this on any system you care about. It’s fine for a quick “is this even a permissions issue?” test on a disposable VM, but never, ever in a production or even a semi-permanent setup.

2. The “Right Way” Permanent Fix: Use PUID & PGID

This is the solution you’re looking for. Most well-built Docker images, especially those from the fine folks at linuxserver.io, allow you to specify the user and group ID the container should run as. This is done through environment variables, typically `PUID` (Process User ID) and `PGID` (Process Group ID).

The goal is to match the container’s user ID with the host user ID that owns the files. Here’s how:

Step 1: Find your user’s ID on the host.

SSH into your OpenMediaVault server or Docker host. Let’s say your user is named `media_manager`. Run the `id` command:

id media_manager

You’ll get an output like this:

uid=1001(media_manager) gid=100(users) groups=100(users),27(sudo)

The important numbers here are `uid=1001` and `gid=100`.

Step 2: Update your Docker Compose file.

Now, edit your `docker-compose.yml` for Immich (or whatever app is giving you trouble) and add an `environment` section:

version: '3.8'

services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:release
    # ... other settings ...
    environment:
      - PUID=1001
      - PGID=100
      - TZ=America/New_York
    volumes:
      - /path/to/your/immich/library:/usr/src/app/upload
    # ... rest of the config ...

When you restart the container (`docker-compose up -d`), the entrypoint script inside the container will use these variables to configure its internal user to run with UID 1001 and GID 100. As far as the host kernel is concerned, the process inside the container is the `media_manager` user, and it will be granted the correct permissions.

3. The ‘Nuclear’ Option: Run as Root

Sometimes, an image doesn’t support PUID/PGID, or you’re dealing with a really strange permissions issue where you just need ultimate power. In these rare cases, you can force the container to run as the root user (UID 0, GID 0).

version: '3.8'

services:
  some-problem-app:
    image: some/image
    user: "0:0" # This is the magic line
    volumes:
      - /some/host/path:/data
    # ... rest of the config ...

By adding `user: “0:0″`, you are telling Docker to run the main process in the container as the root user. Since root can do pretty much anything, this usually solves the permission error. However, it’s a massive security risk. If an attacker compromises your application, they now have root access inside the container, which is a much more privileged position to attack your host system from.

WARNING: This is a last resort. Running containers as root breaks the principle of least privilege. Only use this if you fully understand the security implications and have exhausted all other options.

Quick Comparison Table

So next time you see that ‘Permission Denied’ error, don’t reach for the `chmod 777` hammer. Take a deep breath, find your PUID/PGID, and fix it the right way. Your future self will thank you.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions