You copied 400 movies onto the NAS, pointed Plex at the folder, hit scan, and got back a library with exactly zero items in it. No error popup, no warning, just an empty grid staring at you.
That was my Saturday afternoon about three years ago, and it turned out to have nothing to do with the files themselves.
The drive was healthy, the paths were correct, and the media played fine when I opened it directly. Plex simply was not allowed to read the folder. This is the single most common reason a Plex library scans empty on a NAS, and once you understand who Plex thinks it is, the fix takes about ten minutes.
Why Plex cannot see files that are clearly there
On Linux based systems, and that includes Synology DSM, Unraid, and every Docker container, every file has an owner and a group. It also has a set of permissions deciding who can read, write, or execute it.
When Plex runs inside Docker, it does not run as you. It runs as a user identified by two numbers: a PUID (the user ID) and a PGID (the group ID). If those numbers do not match the owner of your media folder, Plex gets told no, and a rejected read looks exactly like an empty folder to the scanner.
The error hiding in your logs usually reads something like "Error: Permission denied" or "failed to open dir, permission denied" next to the path it tried to scan.
Step 1: Find out who Plex actually is
Before you change anything, find the two numbers Plex is using. On Unraid, open the Plex container settings and look at the PUID and PGID variables, they are right there in the template.
On Synology or any setup where you run Plex through Container Manager or a compose file, open the file and read the environment block. You are looking for two lines like PUID=1000 and PGID=1000.
If you cannot find them, SSH into the box and run this against the running container. It prints the user Plex sees.
docker exec -it plex id
You will get back something like uid=1000 gid=1000 groups=1000. Write those two numbers down. Everything else depends on them.
Step 2: Find out who owns the media folder
Now check the folder Plex is trying to read. SSH in and run this against your actual media path.
ls -ln /volume1/media/movies
The lowercase n matters, it shows numeric IDs instead of names. You will see two numbers per line, the first is the owner UID and the second is the group GID. Compare them to the PUID and PGID from Step 1.
If Plex is 1000:1000 and your files are owned by 1024:100, that gap is your whole problem. The scanner is knocking on a door it does not have a key to.
Step 3: Match the two, and pick a direction
You have two clean ways to close the gap, and I have used both depending on the NAS.
Option A, change the folder to match Plex. Point the media ownership at the PUID and PGID Plex already uses. This is my preferred route on Unraid because the whole array is built around the nobody:users pair (99:100).
Option B, change Plex to match the folder. Edit the PUID and PGID variables in the container to match whoever already owns the files, then restart the container. This is often cleaner on Synology where a shared folder was created by a specific user you do not want to disturb.
| Approach | Best for | Risk level |
|---|---|---|
| Change folder ownership (chown) | Unraid, fresh media shares | Medium, wrong path is dangerous |
| Change Plex PUID/PGID | Synology, existing shared folders | Low, only restarts the container |
| Add Plex user to the folder group | Mixed setups, shared writers | Low, no ownership rewrite |
Doing Option A safely
Once you are certain of the path, set the owner and group to match Plex. For a linuxserver image running as 1000:1000, that command is straightforward.
chown -R 1000:1000 /volume1/media/movies
The R makes it recursive so every file and subfolder underneath gets the same owner. On a library of a few thousand files this finishes in seconds. On tens of thousands it can take a minute or two, which is normal, let it run.
Doing Option B safely
Edit the container so PUID and PGID equal the numbers you saw in Step 2. In a compose file that is two lines under environment. In Unraid or Container Manager it is two fields in the edit screen. Save, then recreate or restart the container so it picks up the new identity.
Step 4: Fix the permission bits, not just ownership
Ownership is only half of it. Even a correctly owned file can be unreadable if the permission bits are wrong, which happens a lot after copying from a Windows machine or an old external drive.
The safe target for media is 755 on folders and 644 on files. That means the owner can read and write, and the group and everyone else can read. Plex only needs to read, so read is enough.
You can set folders and files correctly in one pass with find, which avoids making video files executable.
find /volume1/media/movies -type d -exec chmod 755 {} ;
find /volume1/media/movies -type f -exec chmod 644 {} ;
The first line handles directories, the second handles files. Run both. If Plex still cannot enter a folder, it is almost always a directory missing that execute bit, which on folders means "allowed to open".
Step 5: Rescan and confirm
Go back into Plex, open the library settings, and choose Scan Library Files. If the ownership and bits are right, items start appearing within a few seconds.
Still empty? Check the Docker volume mapping. A frequent trap is that the path Plex sees inside the container (for example /media) is mapped to a host path that does not actually contain the files, so permissions were never the issue at all.
You can verify from inside the container with docker exec -it plex ls -la /media and see whether Plex can list your folders at all. If that command shows your movies, the mapping is fine and the fix landed.
The linuxserver.io team keeps clear notes on how PUID and PGID work across all their images, and it is worth a read if you run more than just Plex. See the official Docker container run reference for how volume mounts and users interact, and Synology's own shared folder permissions guide for the DSM side.
Keeping it from breaking again
The reason this bites people twice is that new files arrive with the ownership of whatever created them. If your download client runs as a different user than Plex, every new episode lands with the wrong owner and disappears from the scan.
The durable fix is to run Plex and your downloaders under the same PUID and PGID, and to point them all at a single shared group. Once every app in the media chain shares one identity, new files inherit the right permissions and Plex just sees them.
Set it up once with matching IDs, and the empty library problem stops being a Saturday afternoon and becomes a thing you never think about again.
Frequently asked questions
What PUID and PGID should I use for Plex on a NAS?
There is no single correct number, the goal is that Plex's PUID and PGID match whoever owns your media folder. The linuxserver.io Plex image defaults to 1000:1000. On Synology, check the folder owner with ls -ln first, then set Plex to those numbers or chown the folder to match.
My Plex library scans empty but the files play fine directly. Why?
Playing a file directly uses your login, which has access. The Plex scanner runs as a different Docker user and gets permission denied, which looks like an empty folder. Match the container's PUID and PGID to the folder owner and rescan.
Is it safe to run chown -R on my media folder?
Yes, as long as you target only the media folder and not a system path. Running chown -R against /volume1 or / can break DSM and force a repair. Double check the exact path before pressing enter, and it only touches ownership, not the files themselves.
Do I need to fix permission bits as well as ownership?
Often yes. Correct ownership does not help if the bits are wrong, which is common after copying from Windows or an old drive. Set folders to 755 and files to 644 so Plex can read them; folders need the execute bit to be openable.
Why do new episodes keep disappearing from Plex after I fix it?
New files arrive with the ownership of whatever app created them. If your download client runs as a different user than Plex, every new file has the wrong owner. Run all your media apps under the same PUID and PGID so new files inherit the right permissions.
