🐳 The Volume That Mounted Fine and Still Refused Every Write
A bind-mounted volume showing up correctly inside a container – visible, readable, present at the expected path – can still reject every write with a permission error, because the process running inside the container has its own user ID, and that UID is checked against the HOST folder’s actual file permissions, not against anything Docker itself manages. A container process running as UID 1000 writing into a host folder owned by a different UID (or owned by root with restrictive permissions) gets denied, regardless of how the volume mount itself is configured.
🔎 The Problem
docker run -v /home/user/app-data:/data myapp # Inside the container: ls -la /data # Shows the files fine - the mount itself works. touch /data/test.txt # Permission denied # The container'"'"'s process runs as UID 1000 (a non-root user set in the # Dockerfile via USER 1000) - but the host folder /home/user/app-data # is owned by UID 1001 (a different user on the host machine) with # permissions that only allow that specific owner to write. Docker # faithfully mounted the folder exactly as it exists on the host - # ownership and all - it never changes file ownership to match # whatever user happens to be running inside the container.
✅ Fix: Match the Container’s User to the Host Folder’s Ownership
- Running the container with –user matching the host folder’s actual owning UID/GID (docker run –user 1001:1001 …) is the most direct fix – the container process then has exactly the permissions on that mount that the matching host user would have.
- Where the UID needs to be decided at build time rather than run time, an ARG for UID/GID passed during docker build, used in a Dockerfile’s USER instruction, keeps the image’s internal user aligned with whichever host environment it gets deployed into, without hardcoding a single UID that only works on one machine.
- chown-ing the host folder to match the container’s expected UID ahead of time (or as an init step run once as root before dropping to the non-root user) is the more common approach in practice, since it avoids needing to know or configure a specific UID per host at all.
⚠️ Why This Passes Locally but Fails Elsewhere
- A developer running the exact same container as root locally (either because a Dockerfile doesn’t specify USER, or because their local Docker setup happens not to enforce this the same way) sees this work perfectly – the permission error only appears once the same image runs with a non-root user, which security-conscious production configurations often require explicitly.
- The UID mismatch is invisible from the Dockerfile or docker-compose.yml alone – both files can look completely correct, since neither one controls what UID actually owns files on the host machine the container happens to run on, which varies by which machine (and which host user) actually launched it.
A volume mount hands a container the host’s files exactly as they are, ownership included – it was never Docker’s job to rewrite who owns them just because a different user is asking to write now.
