"Permission denied" — what PUID and PGID are, and the fix

Published 26 August 2026 · Updated 18 September 2026 · SparkBox team

Radarr says the root folder isn't writable. Immich's log says EACCES. The checkup says "PUID not set in .env — containers fall back to root". Different symptoms, one cause: the apps run as one user, and the folder belongs to another. Here is the idea in plain words and the two commands that settle it.

1. What PUID and PGID actually are

Every file on Linux has an owner — a user number and a group number. Every SparkBox app also runs as a user number: that is PUID (user) and PGID (group) in /opt/sparkbox/.env. When the app's number matches the folder's owner, it can read and write. When it doesn't, you get "permission denied", "read-only", or an app that can see files but never imports them.

At install, SparkBox sets both to the user you installed as — usually 1000 on a fresh Linux box; UGREEN, Synology and other NAS systems use their own numbers. Find yours with:

id            # prints uid=1000(you) gid=1000(you) …

2. Checkup says "PUID not set"

Then the apps are running as root. They can write anywhere — which sounds fine until every file they create belongs to root and the next tool (your file manager, a backup, Jellyfin) can't touch them. Set both to your user and restart:

sudo sparkbox set-env PUID 1000
sudo sparkbox set-env PGID 1000
sudo sparkbox up

Files the apps already created as root now belong to the wrong owner — fix them once with the command in section 3, on your media and data folders.

3. One folder refuses writes

Typical after moving your library to a new drive (pointing SparkBox at existing NAS media), copying with sudo cp, or restoring from a backup as root. Give the folder back to your user, recursively:

sudo chown -R 1000:1000 /path/to/folder      # your PUID:PGID
sudo chmod -R u+rwX,g+rwX /path/to/folder

Common paths: your media root (Settings → Server Config → Media → Media Root, default /opt/sparkbox/data/media), the photo library (Photos Path), and the app's own config at /opt/sparkbox/modules/<app>/config. Restart the app afterwards (Apps → app → Restart) so it re-checks.

4. NAS-specific: the folder belongs to the NAS's admin user

On UGREEN and Synology, files created through the NAS's own apps are owned by the NAS admin user, not by the Linux user SparkBox runs as. Two clean options:

• Set PUID/PGID to that user's numbers (run id <nas-username> over SSH), so the apps and the NAS agree; or
• Keep SparkBox's numbers and chown the shared folder as in section 3 — but the NAS's own apps may then see it as "not theirs".

The first option is the one we run on our UGREEN test box.

5. When it is not a permissions problem

• "Root folder does not exist" in Radarr/Sonarr — a path, not a permission: fix-sonarr-root-folder.
• Immich says permission denied on its library after an upgrade — a known Immich-specific case with its own steps: Immich permission fix.
• The VPN container can't write its config — Gluetun permission fix.

Frequently asked

What are PUID and PGID?

The user and group number the apps run as. If they don't match the folder's owner, the app can't write. SparkBox sets them to your login user at install.

Why did this start after I moved my media to a new drive?

Copying with sudo, or through a NAS file manager, often makes root or the NAS admin user the owner. One chown on the folder fixes it.

Is it safe to just run everything as root?

It works — that is what happens when PUID is missing — but every file the apps create then belongs to root, which breaks the next tool that touches them. Set PUID/PGID to your user.