Copying a file into a Docker container’s volume on a NAS can return “Permission denied” or show a folder owned by a user named `1000`. That error is a frequent obstacle for home labbers and small business admins. NAS Docker volume permissions account for many of these failures. The container works and the app runs, but the data becomes inaccessible as soon as you access it from the NAS file manager. The explanation below covers why it happens and how to fix it so the change lasts. (Docker (software)))
Why Docker Volume Permissions Get Messy on a NAS
Docker named volumes are created and managed by the Docker daemon. On most systems, that daemon runs as root by default. When a container writes files into a volume, those files inherit the UID (user identifier) and GID (group identifier) of whatever user the process inside the container runs as. If that process runs as root, files land as root-owned. If the container image specifies a non-root user, files land owned by that UID, which may not exist as a real account on your NAS at all. (Docker Volumes documentation)
Here is the catch that trips people up: bind mounts behave completely differently from named volumes. A bind mount maps a folder on your NAS directly into the container, so host ownership and permissions are preserved exactly. A named volume, by contrast, gets initialized from the image’s directory contents and ownership the first time it is used. That difference explains why the same app can behave perfectly with a bind mount and fail with a named volume.
On a NAS specifically, there is an extra layer. Devices from Synology, QNAP, and TrueNAS run Docker (or Container Manager) under the NAS’s own user and permission model, which often includes ACLs (access control lists) and shared-folder permissions. So the container’s UID/GID mapping and the NAS’s ACL system interact in ways that simply do not happen on a plain Linux server. A permission rule that works on a vanilla Ubuntu box can quietly fail on a NAS because the NAS is enforcing an additional access check on top.
The Symptoms You Will Recognize
Before diagnosing, it helps to name the problem. Most people hit one of these:
- The container starts but crashes with “Permission denied” when writing to its data folder.
- Files appear in the NAS file manager but cannot be opened, edited, or deleted by your normal user.
- A folder shows an owner like `1000:1000` or `999:999` that does not match any NAS account.
- The app works until you reboot the NAS, then permissions seem to reset.
- Copying files in via the NAS interface works, but the container cannot read them.
Each of these points to the same root cause: a mismatch between the UID/GID the container uses and the UID/GID that owns the data.
The Four Fixes That Actually Work
1. Run the Container as the Right User
The cleanest fix is to tell Docker which user the container should run as, using the `–user` flag (or `user:` in a compose file). Match it to the UID and GID that own your data folder on the NAS.
For example, if your NAS user owns the shared folder with UID `1026` and GID `100`, you would start the container with `–user 1026:100`. The container then writes files owned by that user, and your NAS file manager can read them normally.
The tradeoff: some images expect to run as root internally and will fail if you force a different user. Check the image documentation first.
2. Use PUID and PGID Environment Variables
Many popular self-hosted images (the LinuxServer.io family being the best-known example) support PUID and PGID environment variables. Instead of forcing a user at the Docker level, you pass the IDs in and the image’s startup script handles the `chown` for you.
This is often the most beginner-friendly path on a NAS because it does not require you to understand the image’s internals. You simply set:
| Variable | What It Does | Example Value |
|---|---|---|
| PUID | Sets the user ID the app runs as | 1026 |
| PGID | Sets the group ID the app runs as | 100 |
| UMASK | Controls default file permissions | 002 |
Not every image supports these variables, so verify before relying on them.
3. Chown Inside the Container at Startup
Some images include an init step that runs `chown -R` on the data directory every time the container starts. This works, but it has a cost: on a large volume, that recursive ownership change can slow startup significantly, and it can mask a deeper configuration problem. It is a reasonable stopgap, not a permanent strategy.
4. Use a Bind Mount Instead of a Named Volume
If permissions keep fighting you, switching from a named volume to a bind mount often resolves the issue instantly. With a bind mount, you control the folder on the NAS directly. You set its ownership once, in the NAS file manager or via SSH, and the container respects it.
The tradeoff is portability: a bind mount ties the container to a specific path on that specific NAS. For a single-device home lab, that is usually a fine trade.
A Practical Step-by-Step Workflow
Here is a sequence that works reliably on most NAS setups. It assumes you have SSH access, which most NAS models allow you to enable.
- Find the UID and GID of your NAS user. Run `id yourusername` over SSH. Note the numbers.
- Locate the data folder. Identify whether the container uses a named volume or a bind mount by inspecting its configuration.
- Set ownership on the host folder (for bind mounts) with `chown -R UID:GID /path/to/folder`.
- Set permissions with `chmod -R 775 /path/to/folder` so both owner and group can read and write.
- Configure the container with either `–user UID:GID` or the PUID/PGID variables, depending on what the image supports.
- Restart the container and check the logs for permission errors.
- Verify by creating a test file from inside the container and confirming your NAS user can open it.
If step 7 fails, go back to step 1. Nine times out of ten, the numbers you found do not match what the container is actually using.
Common Mistakes That Waste Hours
Assuming root is the problem when it is not. Many people reflexively add `–user root`, which makes the container work but leaves files owned by root on the host. That just moves the problem to your file manager.
Ignoring the umask. Even with correct ownership, an overly strict umask can produce files that only the owner can read. A umask of `022` gives group and others read access; `077` locks everyone else out. For shared folders, `002` is often the friendliest setting.
Forgetting that ACLs override standard permissions. On a NAS, a shared folder may have ACL entries that take precedence over the classic owner/group/other bits. If `chmod` seems to have no effect, check the ACL view in your NAS control panel.
Changing permissions on the wrong path. It is easy to `chown` a folder that looks right but is actually a symlink or a different mount point. Confirm the real path before running a recursive command.
Running recursive chown on a huge library. A `chown -R` across terabytes of media can take hours and hammer the disks. Do it once, deliberately, and document what you changed.
When to Prefer Bind Mounts vs Named Volumes
The choice shapes how much permission troubleshooting you will face. Here is a straightforward comparison.
| Factor | Named Volume | Bind Mount |
|---|---|---|
| Host ownership preserved | No, initialized from image | Yes, exactly as on host |
| Easy to back up from NAS file manager | Harder, lives in Docker’s area | Easy, it is just a folder |
| Portable between systems | Yes | No, tied to a path |
| Permission friction on NAS | Higher | Lower |
| Best for | Databases, app internals | Media, documents, shared data |
For data you will actually browse and manage from the NAS interface, bind mounts usually cause fewer headaches. For application state that the container manages itself, named volumes are cleaner.
A Note on NAS-Specific Behavior
Each NAS platform handles Docker permissions a little differently. Synology’s Container Manager, QNAP’s Container Station, and TrueNAS SCALE each layer their own user model on top of Docker. The exact UID/GID defaults, ACL behavior, and any version-specific quirks vary by model and firmware, so it is worth checking your platform’s current documentation rather than assuming a fix that worked on another brand will transfer cleanly.
The general principle, though, holds everywhere: the container’s effective UID/GID must match the ownership of the data it touches, and the NAS’s ACL layer must permit that access. Get those two things aligned and the errors disappear.
Conclusion
NAS Docker volume permissions are not really a Docker problem. They are a user identity mapping problem wearing a Docker costume. Once you understand that named volumes inherit ownership from the image while bind mounts inherit it from the host, the fixes become obvious: match the UID/GID, set a sane umask, respect the NAS’s ACL layer, and verify with a real test file rather than assuming. Start with the simplest fix that fits your image, document the IDs you chose, and you will spend far less time debugging and far more time actually using your self-hosted apps.
Frequently Asked Questions
Why do my Docker files show up owned by 1000 on my NAS?
UID `1000` is the default first non-root user on many Linux systems, and many container images run their process as that user. If no NAS account with UID 1000 exists, the file manager shows the raw number instead of a name. The fix is to align the container’s user with a real NAS account using `–user` or PUID/PGID variables.
Should I just run the container as root to fix permissions?
It will make the container work, but it creates files owned by root on the host, which your normal NAS user then cannot edit or delete. That simply moves the problem to your file manager. Running as the correct non-root UID is the better long-term choice.
What is the difference between a bind mount and a named volume for permissions?
A bind mount maps a host folder directly into the container and preserves the host’s ownership and permissions exactly. A named volume is managed by Docker and gets initialized from the image’s directory contents and ownership on first use. That difference is why the same app can fail with one and work with the other.
How do I find the right UID and GID to use?
Over SSH, run `id yourusername` on the NAS. The output lists your numeric UID and GID. Use those exact numbers in your container configuration. If the numbers do not match what the container is actually using, permissions will still fail.
Why does chmod seem to have no effect on my NAS folder?
Your NAS likely enforces ACLs on shared folders, and ACL entries can override the classic owner/group/other permission bits. Check the ACL view in your NAS control panel and adjust the entries there rather than relying on `chmod` alone.
Can I fix permissions without using the command line?
Often, yes. Many NAS interfaces let you set folder ownership and permissions through a graphical file manager, and many popular container images accept PUID and PGID environment variables that handle the rest at startup. SSH is only required when the graphical tools cannot express the change you need.
