Plex problems¶
This page covers Plex Media Server, the NAS mount that Plex reads, the Plex watchdog, and the Plex to TVmaze sync. Run the checks as admin on the server unless a step says otherwise.
For how these parts work, see Plex setup, Plex watchdog and TVmaze scrobble.
Plex does not answer on port 32400¶
Cause
- The
operatoraccount is not logged in. Plex and the NAS mount start fromoperatorLaunchAgents, which start only in a desktop session of that account. - Plex is running but hung. On one server the Plex database deadlocked after its weekly database optimization, and Plex stopped answering every request.
- The Plex watchdog restarted Plex once, Plex stopped answering again within an hour, and the watchdog stopped trying.
Check
pgrep -fl 'Plex Media Server'
curl -s -o /dev/null -w '%{http_code}\n' --max-time 10 http://localhost:32400/identity
sudo launchctl print gui/$(id -u operator)/com.<hostname>.plexmediaserver | grep -E 'state|last exit'
- No process from
pgrepand000fromcurlmeans Plex is not running. - A process from
pgrepand000or503fromcurlmeans Plex is running but does not answer. 200means Plex answers. Look at the client or the network instead.- An error from
launchctl printmeans the agent is not loaded, usually becauseoperatoris not logged in.
Then read what the watchdog did, and look for the deadlock signature in the Plex log:
sudo grep -iE 'restart|unreachable' /Users/operator/.local/state/plex-watchdog.log | tail -20
sudo grep -c 'threads are waiting on db connections' \
"/Users/operator/Library/Logs/Plex Media Server/Plex Media Server.log"
not restarting again means the watchdog gave up and waits for you. Not restarting Plex: an update may be running means it waits for an update. Automatic restart is off means the file ~/.config/plex-watchdog/no-restart exists in the operator account. A count above zero from the second command points to a database deadlock.
Fix
- If
operatoris not logged in, restart the Mac mini.operatorlogs in automatically. - If Plex is hung, wait for the watchdog. It restarts Plex after 3 failed polls (about 15 minutes), unless a Plex update or a
brew upgradeis in progress. -
To restart Plex by hand, open Terminal in the
operatordesktop session (at the Mac mini or through Screen Sharing). Plex ignores SIGTERM, so stop it and its helpers with SIGKILL, then start it withopen, as the watchdog does: -
Confirm that Plex opened its real database, not an empty one:
The path must be under
/Users/operator/Library/Application Support/Plex Media Server. -
When Plex answers again, the watchdog clears its "gave up" state on its next poll.
Plex shows an empty, unclaimed server¶
Cause
The Plex LaunchAgent starts Plex with PLEX_MEDIA_SERVER_APPLICATION_SUPPORT_DIR=/Users/Shared/PlexMediaServer. The real Plex data is in ~/Library/Application Support/Plex Media Server of the operator account. The link /Users/Shared/PlexMediaServer/Plex Media Server must point at the real data. If the link is missing or is a real folder, a Plex that the LaunchAgent starts creates a new, empty server there. The nightly database backups can also go to the wrong place.
Check
ls -ld "/Users/Shared/PlexMediaServer/Plex Media Server"
lsof -p "$(pgrep -f 'MacOS/Plex Media Server$')" | grep library.db
sudo grep -E 'data link|REPAIRED' /Users/operator/.local/state/plex-watchdog.log | tail -5
The first line must start with l and end with -> /Users/operator/Library/Application Support/Plex Media Server. A line that starts with d means a real folder is in the way. The lsof line shows which database the running Plex uses.
Fix
- If the link points at the wrong place or is missing, wait up to 5 minutes. The watchdog repairs it and logs
REPAIRED. -
If it is a real folder, the watchdog does not touch it. Move it aside:
-
Wait for the next watchdog run to create the link.
- If the running Plex uses the empty database, restart Plex as in Plex does not answer on port 32400, and check the
lsofline again.
Plex libraries are empty or files show as unavailable¶
Cause
- The NAS share is not mounted in the
operatoraccount. The mount agent retries every 2 minutes, but it cannot mount while the NAS is unreachable. - A macOS privacy prompt about network volume access is open on the desktop, and Plex waits for it.
- The NAS export does not allow the server, or it does not allow non-privileged ports.
The Plex watchdog checks this with a real file read. After 2 failed checks it sends the email Plex cannot read media files.
Check
mount -t nfs
sudo -iu operator ls /Users/operator/.local/mnt/<share>
sudo launchctl print gui/$(id -u operator)/com.<hostname>.mount-nas-media | grep -E 'state|last exit'
sudo tail -20 /Users/operator/.local/state/<hostname>-mount.log
mount -t nfsmust list/Users/operator/.local/mnt/<share>.NFS mount failedorFailed to establish network connectivityin the mount log means the NAS did not answer or refused the mount.- If the mount is listed but
lshangs or fails withOperation not permitted, look at the desktop for a privacy prompt. See A privacy prompt blocks the server.
Fix
- Make sure that the NAS is on and reachable:
ping -c 3 <NAS hostname>. -
Run the mount agent now instead of waiting for its next run:
The script returns at once when the share is already mounted. It does not unmount a working mount.
-
If the mount still fails, check the NFS export on the NAS. It must allow the server's address, read and write access, and non-privileged ports. See NAS storage configuration.
- If a privacy prompt is open, click Allow.
Do not unmount the share on the host to "refresh" it. Plex reads from it, and the Transmission container sees it through VirtioFS.
The Plex watchdog reports settings drift¶
Cause
A Plex setting changed from the value in the golden config. Someone changed it in the Plex web app, or a Plex update changed it.
Check
sudo -iu operator plex-watchdog-ctl status
sudo grep 'DRIFT DETECTED' /Users/operator/.local/state/plex-watchdog.log | tail -10
status shows the golden and current value of each monitored setting.
Fix
- To keep the new value, run
sudo -iu operator plex-watchdog-ctl accept. - To put the golden value back into Plex, run
sudo -iu operator plex-watchdog-ctl revert. - If a fresh setup reports drift, run
sudo -iu operator plex-watchdog-ctl refreshto read all settings again.
The Plex watchdog does not run¶
Cause
The watchdog is an operator LaunchAgent. It runs only while operator is logged in, and only if its plist is loaded.
Check
sudo launchctl print gui/$(id -u operator)/com.<hostname>.plex-watchdog | grep -E 'state|last exit|run interval'
sudo tail -5 /Users/operator/.local/state/plex-watchdog.log
state = not running between runs is normal: the job runs every 300 seconds and exits. An error from launchctl print means the job is not loaded. The log has an OK: heartbeat line about once an hour when nothing is wrong.
Fix
-
If the job is not loaded, load it:
-
To run it now, run
sudo launchctl kickstart -kp gui/$(id -u operator)/com.<hostname>.plex-watchdog. A run can send email and can restart a Plex that does not answer. - If the log says
alert library not foundortoken file not found, runplex-watchdog-setup.shagain.
The watchdog says Plex answers /identity but the prefs request fails¶
Cause
The Plex token in ~/.config/plex-watchdog/token of the operator account was revoked or changed. /identity needs no token, so Plex looks alive, but every authenticated request fails. The watchdog does not restart Plex in this case.
Check
sudo -iu operator bash -c \
'curl -s -o /dev/null -w "%{http_code}\n" -H "X-Plex-Token: $(cat ~/.config/plex-watchdog/token)" http://localhost:32400/:/prefs'
200 means the token works. 401 means the token must be replaced.
Fix
- Put a valid token in
plex.tokenof/Users/operator/.config/transmission-done/config.yml.plex-watchdog-setup.shreads the token from that file. - Run
plex-watchdog-setup.shagain. It checks the token and writes the token file at mode 600.
Plex waits for an administrator password during an update¶
Cause
The Plex app in /Applications is owned by root. The Plex updater cannot write it, so it opens a password dialog on the desktop and waits. plex-setup.sh gives operator ownership of the app so that updates install without a dialog. The daily brew upgrade job skips the Plex cask for the same reason.
Check
stat -f '%Su:%Sg' "/Applications/Plex Media Server.app"
sudo -iu operator defaults read com.plexapp.plexmediaserver ButlerTaskUpdateServer
The owner must be operator:staff, and the setting must be always.
Fix
- Answer the dialog on the desktop, if one is open.
-
Run
plex-setup.shagain, or giveoperatorownership of the app:A change of owner changes the time stamp of the Plex binary. The watchdog then waits 30 minutes before it restarts Plex.
Watched episodes do not appear on TVmaze¶
Cause
- The Plex webhook is not set, or it points at the wrong address.
- The listener is not running.
- The worker cannot match the show, or TVmaze refused the request.
Check
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:32599/
sudo grep -E 'webhook:|SYNCED|FAILED|ERROR' /Users/operator/.local/state/tvmaze-scrobble.log | tail -20
200 means the listener answers. No webhook: lines after a play means Plex did not send the webhook. FAILED: and ERROR: lines give the reason for each episode.
Fix
- In the Plex web app, signed in as the server owner, open Settings, then Webhooks. Add
http://127.0.0.1:32599/plex. -
If the listener does not answer, restart it:
-
To sync plays that the webhook missed, run the reconcile job now:
-
For
ERRORlines about credentials or the Plex token, runtvmaze-scrobble-setup.shorplex-watchdog-setup.shagain, as the line says.