Docker volumes: fix permissions in 3 commands

The mechanism: why Docker refuses to write

Most affected applications and their UIDs

• Paperless-ngx — UID 1000 (user paperless): manages consume, export, media and data directories
• Grafana — UID 472 (user grafana): writes SQLite database and plugins to /var/lib/grafana
• Nextcloud (Debian image) — UID 33 (user www-data): data directory, config and logs
• Immich — UID 1000 (user node): photo library, thumbnails and ML database
• Gitea — UID 1000 (user git): repositories, SSH keys, logs and default SQLite database

Diagnosis: identify the problem in under 2 minutes

1. 01

   Read the exact error message

   Check the logs of the affected container:

   docker logs <container-name> 2>&1 | grep -i 'permission\|denied\|cannot\|mkdir'

   A permission denied or cannot create directory message confirms the diagnosis.

2. 02

   Identify the process UID inside the container

   docker exec <container-name> id

   Typical output: uid=472(grafana) gid=0(root). Note the UID — here 472.

3. 03

   Check the host directory owner

   ls -ln /opt/grafana/data

   Output drwxr-xr-x 2 0 0 ... means the directory is owned by root (UID 0). UID 472 only has "other" rights — read and execute, no write.

4. 04

   Use stat for a complete diagnosis

   stat /opt/grafana/data

   Check the Uid: and Gid: lines. If they show (0/root) while your container runs as 472, the problem is confirmed.

5. 05

   Inspect the container configuration

   docker inspect <container-name> | grep -A5 'Mounts'

   This command lists all active bind-mounts and named volumes, with their host source and container destination.

Fix by case: chown on the host directory

1. 06

   Grafana (UID 472)

   mkdir -p /opt/grafana/data
   chown -R 472:472 /opt/grafana/data

   In your compose.yml:

   volumes:
     - /opt/grafana/data:/var/lib/grafana

2. 07

   Nextcloud (UID 33, Debian image)

   mkdir -p /opt/nextcloud/{data,config,apps}
   chown -R 33:33 /opt/nextcloud/data
   chown -R 33:33 /opt/nextcloud/config

   Note: the Alpine image uses UID 82. Verify with docker exec <container> id www-data if you're unsure which variant you're using.

3. 08

   Paperless-ngx (UID 1000)

   mkdir -p /opt/paperless/{consume,export,media,data}
   chown -R 1000:1000 /opt/paperless/consume
   chown -R 1000:1000 /opt/paperless/export
   chown -R 1000:1000 /opt/paperless/media
   chown -R 1000:1000 /opt/paperless/data

4. 09

   Immich (UID 1000)

   mkdir -p /opt/immich/{library,thumbnails,encoded-video,profile}
   chown -R 1000:1000 /opt/immich

   Note: PUID/PGID environment variables do NOT work with official Immich images. They are specific to LinuxServer.io images.

5. 10

   Verify after correction

   ls -ln /opt/grafana/data

   Should show drwxr-xr-x 2 472 472 .... Then restart the container:

   docker compose restart grafana
   docker logs grafana --tail 20

Variants: bind-mounts, named volumes and user:

services:
  app:
    image: my-image
    user: "1000:1000"
    volumes:
      - /home/user/data:/app/data

NFS and remote mounts

//server/share /opt/nextcloud/data cifs uid=33,gid=33,credentials=/etc/cifs-creds,iocharset=utf8 0 0

Fix methods: comparison

Scroll the table

Troubleshooting: 4 classic errors with their exact messages

• mkdir: cannot create directory '/var/lib/grafana/plugins': Permission denied → Host directory doesn't belong to UID 472. Apply chown -R 472:472 /opt/grafana/data.
• [Errno 13] Permission denied: '/usr/src/paperless/media' → Paperless-ngx can't write to its media directory. Verify the bind-mount belongs to UID 1000 on the host.
• Could not create lock file /var/lib/grafana/.~lock.grafana.db → Grafana can read the directory but not write to it. Permissions issue on existing files: chown 472:472 /opt/grafana/data/*.db or delete the lock file.
• chown: changing ownership of '/data': Operation not permitted (at container startup) → The image tries to fix permissions itself but can't because it doesn't run as root. Perform chown manually on the host BEFORE starting the container.

Conclusion