Troubleshooting

For expected configuration and runtime status, also see Configuration reference, Scan your media library, and Media and thumbnails.

Thumbnails not showing / permission denied errors

Symptoms:

• Images load but thumbnails never appear
• Docker logs contain EACCES: permission denied or mkdir ... EACCES (-13)
• The cache folder, or a subfolder such as cache/thumbs, is owned by the wrong user

Cause:

PICR runs inside the container as UID 1000. If the cache folder on the host was created by Docker automatically (or by root), PICR cannot write thumbnails into it.

If your Compose file sets a custom user: "<uid>:<gid>", use that UID/GID instead of 1000:1000 for the cache folder. This is common when CAN_WRITE=true is enabled for a NAS media mount, because the container user often needs to match the NAS media owner. The cache volume must be writable by the same container user. For example, a container running as user: "1026:100" needs the host cache folder, including cache/thumbs, to be writable by 1026:100.

Fix:

Stop the container, fix ownership of the cache folder, then restart:

Reset cache ownership for the default container user

docker compose down
sudo chown -R 1000:1000 ./cache
docker compose up -d

For a custom container user, replace 1000:1000 with the UID/GID from your Compose file:

Reset cache ownership for a custom container user

docker compose down
sudo chown -R 1026:100 ./cache
sudo find ./cache -type d -exec chmod 775 {} +
sudo find ./cache -type f -exec chmod 664 {} +
docker compose up -d

Thumbnails will regenerate automatically once the container has write access.

You can verify cache write access from inside the running container:

Verify cache writes from inside PICR

docker compose exec picr sh -lc '
set -eu
id
stat -c "%n owner=%u:%g mode=%A" /home/node/app/cache /home/node/app/cache/thumbs
mkdir -p "/home/node/app/cache/thumbs/__picr_probe__/nested"
echo ok > "/home/node/app/cache/thumbs/__picr_probe__/nested/write-test.txt"
cat "/home/node/app/cache/thumbs/__picr_probe__/nested/write-test.txt"
rm -f "/home/node/app/cache/thumbs/__picr_probe__/nested/write-test.txt"
rmdir "/home/node/app/cache/thumbs/__picr_probe__/nested" "/home/node/app/cache/thumbs/__picr_probe__"
'

Prevention:

Create the cache (and data) folders yourself before the very first docker compose up, as described in Installation. If you let Docker create them it will do so as root.

---

Thumbnails disappeared after restarting

If you deleted the cache folder and restarted, Docker will have recreated it as root — see the fix above.

The safe way to clear the thumbnail cache is to delete the contents of the folder, not the folder itself:

Verify the directory before deleting cache contents

Run this only from the PICR Compose directory after confirming that ./cache is the mounted PICR cache. The command permanently deletes everything matched inside that directory.

Clear cache contents, but keep the cache directory

rm -rf ./cache/*

---

Can’t connect to the Postgres database

If PICR starts but immediately exits with a database connection error, the most common cause is another Postgres instance already using port 5432 on your host.

Both Synology DSM and DaVinci Resolve run their own Postgres servers on 5432 by default.

Fix — expose the container on a different host port in compose.yml:

compose.yml — optional PostgreSQL host port

db:
  ports:
    - '54321:5432'

This does not affect PICR itself (it connects to Postgres inside Docker using the internal port), but it frees up 5432 on the host for other tools.

---

PICR says database migrations failed on first start

PICR retries its startup migrations once after 10 seconds if Postgres is not ready yet. If it still fails, check:

1. The db container is running and healthy (docker compose ps)
2. Your compose.yml includes the healthcheck and depends_on.condition: service_healthy as shown in Installation
3. The DATABASE_URL environment variable matches the credentials in the db service

---

Hardware video acceleration not working

CPU-only is normal for gallery thumbnails

VAAPI does not currently speed up poster/scrub thumbnail generation because the CPU benchmarked faster. Seeing “CPU only” does not mean anything is broken for normal use. These steps only confirm that the GPU is detected for the benchmark and future processing features. See Hardware video acceleration.

If the admin Server Info page shows “CPU only” when you expected VAAPI to be detected, work through these. The reason shown on that page (and in the startup log) tells you which step failed.

1. Are you on the right image? VAAPI drivers ship in the amd64 image only. On arm64 PICR always uses the CPU.

2. Is the render device inside the container?

Check for a render device

docker compose exec picr ls -l /dev/dri

You should see renderD128 (or similar). If it’s missing, add the device mapping to your picr service:

compose.yml — pass through the render device

devices:
  - /dev/dri:/dev/dri

3. Does the container user have permission? PICR runs as node, which must be in the host’s render group. Check the host GID and add it under group_add:

Find the host render-group ID

getent group render        # e.g. render:x:992:  -> use 992

compose.yml — grant render-group access

group_add:
  - '992'

A permission problem usually shows up as a probe failure mentioning the device can’t be opened.

4. Can the GPU actually be used? Inspect VAAPI support from inside the container:

Probe VAAPI inside PICR

docker compose exec picr vainfo --display drm --device /dev/dri/renderD128

A healthy GPU prints a driver line and a list of VAProfile… entries. Errors here point at host drivers rather than PICR.

Common “CPU only” reasons:

• /dev/dri/renderD128 is not available — no device mapped in, or wrong path (set VIDEO_ACCELERATION_DEVICE for a non-default node).
• VAAPI probe failed: … — the device exists but VAAPI couldn’t initialise, usually a permission (render group) or host-driver issue.
• video acceleration is disabled (VIDEO_ACCELERATION=off) — you (or your compose) set VIDEO_ACCELERATION=off.

---

“Copy Link” doesn’t copy anything

Almost always this means PICR is being served over plain HTTP on a LAN address, such as http://192.168.1.50:6900/. Browsers only expose the clipboard API on a secure context — HTTPS, or localhost. On a plain-HTTP LAN address the API simply isn’t there.

PICR falls back to an older copy method in that situation, so the button should still work. If it doesn’t:

1. Copy the URL shown under the link ID in the link editor manually — it is the complete link.
2. Put PICR behind HTTPS. See Publish PICR with HTTPS.

Serving PICR over HTTPS is the real fix, and avoids the same class of problem in other browser features.

Something else?

Check the GitHub Issues — search before opening a new one in case it has already been reported or resolved.