Troubleshooting & FAQ
Most errors in Plinthio carry a code like P301, shown after the message. The full list, with what each means and what to do, is in the in-app docs under Error Codes, and at GET /api/errors. Admins also see the underlying cause in the error and in Admin → Logs.
First Checks
- Admin → Health catches unreachable libraries, missing files and conversion failures.
- Admin → Logs, filtered to errors.
- The container's own output:
docker logs plinthio --tail 200. curl http://<server>:8088/api/healthshould return{"status":"healthy",…}with the version. Docker also marks the container unhealthy if it stops answering.
Libraries and Scanning
| Symptom | Cause and fix |
|---|---|
| A library shows nothing after adding it | Big libraries take a while, so watch Admin → Logs. Check the folder is visible inside the container: the path is under /media, not your host path. Check the library type matches the files (a Movies library ignores .cbz) |
| P200 "Library folder not found" | The folder doesn't exist inside the container. Check the volume mount and MEDIA_DIR |
| P201 | The folder can't be read, or it's empty while the catalog has titles in it. Usually the drive or share isn't mounted, and Plinthio refuses to treat that as everything being deleted. Mount it and scan again |
| P202 "permission denied" | The container user (PUID/PGID, default 1000) can't read the folder. Fix ownership or permissions on the host, or set PUID/PGID |
| New files don't appear | The folder watcher can miss changes on network shares. The scheduled rescan picks them up, or press Scan. Check automatic scanning is on in Admin → Libraries |
| A title vanished | Its file is missing: renamed, moved to another library, or its drive dropped. It's in Admin → Health → Missing files. Put the file back and it returns with progress intact |
| A series is split in two, or volumes are in the wrong series | File names or ComicInfo.xml disagree. Admin → Health shows clashing volume numbers. Fix the names, or set the series in Edit Metadata |
| Episodes in the wrong order, or specials mixed in | Use S01E02-style names. Specials are season 0 (S00E01) |
| Trailers on the Movies shelf | Put them in a Trailers folder or name them with -trailer. See Libraries |
| Movies aren't grouped into a collection | Collections need a TMDB key and at least two films of the collection in the library |
Covers and Metadata
| Symptom | Cause and fix |
|---|---|
| Blank covers | Add a cover.jpg, folder.jpg or poster.jpg next to the files, or match metadata. Every scan retries titles with no cover |
| A cover won't update | Reload the page. An installed app may hold the old cover until it reloads |
| P400 on metadata search | Add a TMDB key in Admin → Metadata |
| P401 | The provider refused the key. For TMDB, paste either the "API Key" or the "API Read Access Token" |
| P402, P403 | The provider is rate-limiting or unreachable. Wait and retry, and check the server has internet access |
| No cast, crew or facts on title pages | Needs a TMDB key. They're fetched when a page first opens |
Video
| Symptom | Cause and fix |
|---|---|
| "Starting playback…" never finishes | Check Admin → Logs for ffmpeg errors. On a slow CPU a transcode may not keep up: pick a lower quality, or set up hardware transcoding |
| P303 | ffmpeg is missing (installs without Docker). Install ffmpeg |
| P304 "Conversion failed" | ffmpeg failed on this file. The log has its error. If it mentions VAAPI, QSV or NVENC, set Admin → Playback to Always the CPU and test again |
| P350 "This browser cannot play this video" | Even the converted stream was rejected. Try Chrome, Edge or Safari. If every browser fails, the file may be damaged |
| P351 | The connection to the server dropped. Press Retry |
| P352 | The media link expired and couldn't be renewed. Reload the page, or sign out and in |
| Hardware transcoding isn't detected | Pass /dev/dri through with the right render group ID, or install the NVIDIA toolkit for NVENC. Press Test in Admin → Playback. See Installation |
| A subtitle track isn't listed | Picture-based subtitles (PGS, VobSub) can't be shown. Add an .srt next to the file |
| No scrub previews | They're made in the background on first play, and only shown on computers |
| No casting button | Chromecast needs Chrome, Plinthio opened over HTTPS, and a Cast device on the same network. AirPlay needs Safari |
Reading and Listening
| Symptom | Cause and fix |
|---|---|
| P308 on a PDF | poppler isn't installed (installs without Docker). Install poppler-utils |
| P309 on a PDF | The PDF is damaged or password-protected. Check it in another reader, and remove the password |
| PDF pages are slow the first time | Each page is rendered once, then cached. Later reads are instant |
| An archive won't open | It may be corrupt, or an unusual RAR version. Repack it as CBZ |
| A manga opens left-to-right | Set the direction in the reader. It's saved for the series. <Manga>YesAndRightToLeft</Manga> in ComicInfo.xml sets it on scan |
| Download says it needs HTTPS | Downloads only work over HTTPS. See Installation |
| A download disappeared on iPhone | Safari may clear storage for sites that aren't installed. Install the app to the home screen |
| No audiobook controls on the lock screen | Install the app to the home screen, and start playback with a tap |
Accounts and Access
| Symptom | Cause and fix |
|---|---|
| P107 | Wrong username or password. Admins can set a new password in Admin → Users |
| P108 | Too many failed sign-ins (10 per 15 minutes per address). Wait. Behind a proxy without TRUST_PROXY, everyone shares one limit |
| Everyone is locked out after one person's typos | Set TRUST_PROXY behind a reverse proxy or tunnel. See Away From Home |
| P109 "can only be used from its home network" | Outside access is off. Use it at home or over Tailscale, or turn it on in Admin → Network |
| P110 "for home use only" | The server allows outside access, but not for this account. Admin → Users → Edit → Can use Plinthio away from home |
| P111 "code is not right" | Use the current code from the app (they change every 30 seconds and work once). Check the phone's clock is set automatically, or use a backup code |
| P112 "two-factor needed away from home" | Sign in at home once and turn on two-factor in Settings → Security |
| P113 "sign-in step expired" | More than five minutes passed, or five wrong codes. Enter your password again |
| P103 | The account has expired. An admin can extend it |
| A user can't see a title others can | Their content limit, unrated setting or Kids Mode, or they hid it themselves (Settings → Hidden titles) |
| A kids account sees nothing | Nothing is kids-safe yet. Turn on a library in Admin → Kids Mode, or press Kids on series pages |
| Signed out on every device | A password change, Sign out of all devices, or jwt.secret was deleted or changed |
Watch Parties
| Symptom | Cause and fix |
|---|---|
| No Watch Together button | Watch parties are off: Admin → Features → Watch parties |
| P601 "Party not found" | The party ended, or the server restarted. Ask the host for a new link |
| P603, P604 | A member's content limit or Kids Mode blocks that title |
| P605 | The party has reached 20 people |
| Friends outside can't join | They need a way to reach the server. See Away From Home |
Updates and Disk Space
| Symptom | Cause and fix |
|---|---|
| No update banner | UPDATE_CHECK=false is set, the server can't reach GitHub, or you dismissed it for this version |
| Something broke after an update | Roll back. See Updating |
| The disk is filling up | config/cache (converted video, thumbnails, PDF pages) can be deleted at any time. Old backups in config/backups can go too |
docker compose up won't start after enabling GPU lines | The machine doesn't have that device. Comment the devices:, group_add: or deploy: lines out again |
FAQ
Does Plinthio change my media files? No. It only reads them. Covers, thumbnails and everything else it makes go in /config.
Can people sign themselves up? No. Only an admin can create accounts, in Admin → Users.
Does video download for offline viewing? No. Books, comics, PDFs and audiobooks can be downloaded. Video files are usually too large for browsers to store reliably.
Can I use Plinthio alongside another media server? Yes. Plinthio only reads your folders, and follows the common naming conventions, so the same folders can be shared.
Can I use it for a paid service? No. Plinthio is licensed under the PolyForm Noncommercial License 1.0.0. You can use, modify and self-host it for any noncommercial purpose. Commercial use needs a separate license from Odd Omens.
How do I get help? Email support@oddomens.com, or report a bug on GitHub. Admins can also use Report a problem in the account menu, which fills in the version and browser for you.
How do I report a security problem? Don't open a public issue. Report it privately on GitHub: the repository's Security tab → Report a vulnerability. Include your version (Admin → Overview, or GET /api/health) and steps to reproduce. Security fixes go into the latest release, so stay on latest or PLINTHIO_TAG=1 to receive them.