Permissions and ownership — the UID/GID trap · Docker & Containers

The most common production storage issue is a container that starts cleanly, connects to everything it needs, and then fails on the first write to its data directory with Permission denied.

The cause is almost never exotic. It is a number.

The kernel only sees numbers

There is no user mapping in a plain bind mount

This is the part that most explanations get wrong, so it is worth being precise.

Without user-namespace remapping, there is no translation at all. A process running as UID 1000 inside a container is UID 1000 on the host. Same number, same kernel credential structure. The container’s mount namespace changes which files are visible; it does nothing to who you are.

What is isolated is /etc/passwd. The container has its own, so UID 1000 might be called node inside and ebrandi on the host. Those names are userspace decoration. When the process calls open(2), the kernel compares the numeric UID and GID in the process credentials against the numeric owner in the inode. It has never heard of either name.

So the rule is simple and absolute:

Ownership on a bind mount is decided by the numbers, on the host filesystem, and the container’s /etc/passwd is irrelevant to it.

Two consequences people find surprising:

Adding a user to /etc/passwd inside the container fixes nothing. The name is new; the number is what mattered.
ls -l inside the container and ls -l on the host can show two completely different owner names for the same file, because each resolves the same number against a different passwd database. A UID with no entry in the container’s passwd file simply prints as the number.

Read-only / Safesee both sides of the same inode— The same file, resolved against two different passwd databases.

HOSTDIR=/srv/appdata
CONTAINER=app

echo '--- host view ---'
ls -lan "$HOSTDIR" | head -5

echo '--- container view ---'
docker exec "$CONTAINER" ls -lan /data | head -5

echo '--- who the container process actually is ---'
docker exec "$CONTAINER" id

Read-only / Safethe numbers agree, the names do not— ls -n forces numeric output on both sides so you compare like with like.

$ ls -lan /srv/appdata ; docker exec app ls -lan /data ; docker exec app id

--- host view ---
drwxr-xr-x 2    0    0 4096 Aug 12 09:31 .
-rw-r--r-- 1    0    0   17 Aug 12 09:31 config.yml
--- container view ---
drwxr-xr-x 2    0    0 4096 Aug 12 09:31 .
-rw-r--r-- 1    0    0   17 Aug 12 09:31 config.yml
--- who the container process actually is ---
uid=1001(app) gid=1001(app) groups=1001(app)

Illustrative output

There is the whole bug in three lines. The directory is owned by 0, the process is 1001, and mode 755 gives “other” no write bit. ls -n is the diagnostic — always pass -n, because the names lie and the numbers do not.

Why a named volume usually works and a bind mount usually does not

This asymmetry confuses people who have used Docker for years.

Named volume, path that exists in the image. When Docker populates an empty volume from the image’s content at that path, it copies ownership and mode along with the files. The postgres image ships /var/lib/postgresql/data owned by its own UID, so the volume comes out owned by that UID, and the container can write. No configuration, no chown, it just works.

Named volume, path that does NOT exist in the image. There is nothing to copy, so Docker creates an empty directory owned by root:root with mode 0755. A container running as a non-root user cannot write to it. This is why adding a new mount point to an existing image suddenly breaks a container that has been running as --user 1001 for a year.

Bind mount, always. Nothing is copied and nothing is created except the directory itself. Whatever ownership the host path has is what the container gets.

Read-only / Safecheck before you deploy— Compare the image's ownership at the mount point against the UID the container will run as.

IMAGE=postgres:16
MOUNTPOINT=/var/lib/postgresql/data

# What UID does the image intend to run as?
docker image inspect "$IMAGE" --format 'USER={{.Config.User}}'

# Who owns the mount point inside the image, numerically?
docker run --rm --entrypoint stat "$IMAGE" -c '%n %u:%g %a' "$MOUNTPOINT"

If USER is empty the image runs as root and nothing will fail — which is exactly why so many images do it, and exactly why you end up with root-owned files on the host.

The fixes, worst to best

Wrong reflex: `chown -R` on the host

This is what everyone reaches for, and it is worth being explicit about why it is the wrong first move rather than merely inelegant.

chown -R fixes today and breaks something else

It does make the error go away. It also:

Changes ownership for whatever else uses that path. chown -R 1001:1001 /srv/appdata on a directory that a host backup agent, rsync job or web server also reads is how you take a second service down an hour later, with a symptom that looks unrelated to the container work you just did.

Does not survive. Restore that directory from backup, rsync it from another host, or re-run the provisioning that created it, and the ownership is back to what it was. The fix has to be reapplied every time, by whoever remembers, and the failure returns at the worst moment.

Does not travel. Move the container to another host and you have a new directory with the original ownership problem, because the fix lived in one operator’s shell history and not in the deployment.

Is a landmine on a large tree. chown -R on a multi-terabyte data directory rewrites the inode of every file. On a running database that is hours of metadata I/O and, on some filesystems, a noticeable stall.

Is genuinely dangerous when the path is wrong. A trailing-slash mistake or an unset variable — chown -R 1001:1001 $DATA/ with DATA empty — is chown -R on /. That host does not boot again.

Use it as a deliberate, scoped, one-off on a directory you created for the container. Do not use it as the answer to “why is this denied”.

Better: run as the UID that owns the data

If the host directory is owned by 1001, run the container as 1001.

docker run -d --name app \
  --user 1001:1001 \
  --mount type=bind,src=/srv/appdata,dst=/data \
  myorg/app:1.4.0

--user accepts numeric IDs that need no entry in the container’s /etc/passwd, which is what makes it work on distroless and scratch images. The trade-off is cosmetic: ps inside the container shows 1001 rather than a name, and any code that calls getpwuid() and does not handle a miss will fail. Some runtimes do.

One thing --user does not do is give you the supplementary groups the image’s user would have had. Add them explicitly:

docker run --user 1001:1001 --group-add 2000 myorg/app:1.4.0

Better: give the group access instead of the owner

When two containers with different UIDs must share one volume, chasing a single owner is a dead end. Pick a GID, put both containers in it, and make the directory group-writable and setgid so new files inherit the group:

Destructiveshared-group setup— Modifies ownership and mode on one host directory. Scoped deliberately: no -R on a parent.

SHARED=/srv/shared
SHARED_GID=2000

install -d -m 2775 -g "$SHARED_GID" "$SHARED"

# Both containers join the group; neither needs to own the directory
docker run -d --user 1001:1001 --group-add "$SHARED_GID" --mount type=bind,src="$SHARED",dst=/data myorg/writer:1.0.0
docker run -d --user 1002:1002 --group-add "$SHARED_GID" --mount type=bind,src="$SHARED",dst=/data myorg/reader:1.0.0

Mode 2775 is the setgid bit plus group write. Without setgid, each container’s new files land in that container’s primary group and the other one loses access to them one file at a time — a failure that appears days later and only for new data.

Best: decide the UID at build time and keep it everywhere

The durable fix is that the number is part of the artefact, not part of an operator’s memory.

FROM debian:12-slim
RUN groupadd -g 1001 app && useradd -u 1001 -g 1001 -m -s /usr/sbin/nologin app
# Create the mount point IN THE IMAGE with the right ownership, so an
# empty named volume inherits it instead of coming out root-owned.
RUN install -d -o 1001 -g 1001 -m 0750 /data
USER 1001:1001

services:
  app:
    image: myorg/app:1.4.0
    user: "1001:1001"
    volumes:
      - app-data:/data
volumes:
  app-data:

That install -d -o 1001 line is the one people leave out, and it is what makes a fresh named volume writable on a host nobody prepared.

User-namespace remapping changes all of this

userns-remap is the one configuration where container UIDs really are translated. With "userns-remap": "default" in daemon.json, the daemon creates a dockremap user, reads its subordinate range from /etc/subuid and /etc/subgid, and maps container UID 0 to the first host UID in that range — typically 100000.

Read-only / Safewhat remapping looks like on disk— Container root writes a file; the host sees it owned by the base of the subordinate range.

$ cat /etc/subuid ; ls -lan /srv/appdata

dockremap:100000:65536

drwxr-xr-x 2 100000 100000 4096 Aug 12 09:44 .
-rw-r--r-- 1 100000 100000   17 Aug 12 09:44 config.yml

Illustrative output

Container UID 1001 becomes host UID 101001. Every ownership decision you made without remapping is now off by 100000, and a bind mount prepared for UID 1001 is unreadable. Enabling remapping on a host with existing bind mounts is a migration, not a toggle — plan the ownership change with it.

What if the volume is shared between two containers with different UIDs?

One writes, the other gets Permission denied, and which one depends on who created the directory first — so the failure is non-deterministic across a rebuild.

The instinct is to make the second container run as the first one’s UID. That works until a third service arrives, and it couples two otherwise independent deployments to one number.

The durable answers, in order:

A shared GID with setgid, as above. Each container keeps its own UID; access comes from group membership. This scales to any number of consumers.
World-writable with the sticky bit (1777, like /tmp). Simple, and acceptable for genuinely shared scratch space. Not acceptable for anything with confidentiality requirements, because every container on the host that mounts it can read everything.
Do not share the volume. If two services need the same data, very often what they actually need is one service that owns the data and an API between them. A shared writable directory between two independently deployed services is a coordination problem dressed up as a storage problem.

What does not work is chmod 777 applied during an incident and never revisited, which is the outcome whenever this is diagnosed at 03:00 without a plan.

Verification that can fail

Read-only / Safeprove writability— Run this as the exact user the workload will use, before the workload does.

IMAGE=myorg/app:1.4.0
HOSTDIR=/srv/appdata
RUNAS=1001:1001

docker run --rm --user "$RUNAS" --mount type=bind,src="$HOSTDIR",dst=/data --entrypoint sh "$IMAGE" -c 'touch /data/.permcheck && rm /data/.permcheck && echo WRITABLE || echo DENIED'

DENIED before you deploy is a five-minute fix. DENIED in an application log at 03:00, from a service that has already accepted traffic, is not.