Media pipeline problems¶
This page covers what happens after a download finishes: the trigger watcher, transmission-done and FileBot, triage, the hourly pending-move/ cleanup, and Catch. Run the checks as admin on the server.
For how the pipeline works, see Transmission and FileBot. In short, a finished download moves like this:
- Inside the container,
transmission-post-done.shwrites a trigger file named after the torrent hash to~operator/containers/transmission/config/triggers/. - The
com.<hostname>.transmission-trigger-watcherLaunchAgent looks in that folder every 60 seconds. For each trigger it maps the container path/datato/Users/operator/.local/mnt/<share>and runs~operator/.local/bin/transmission-done. transmission-doneruns FileBot, moves the files into the library, and asks Plex to scan. If FileBot cannot place a download,transmission-donemoves it toMedia/Torrents/triage/.- On success, the watcher removes the torrent from Transmission but keeps its files. The hourly
pending-move-cleanupremoves the files later, after VirtioFS has released them.
A finished download is not processed¶
Cause
- The trigger watcher is not running.
- The NAS is not mounted on the host, so the mapped path does not exist. The watcher logs a warning and tries again on the next poll.
transmission-donefailed 5 times. The watcher renamed the trigger to<hash>.deadand stopped trying.
Check
sudo launchctl print gui/$(id -u operator)/com.<hostname>.transmission-trigger-watcher | grep -E 'state|last exit'
sudo ls -la /Users/operator/containers/transmission/config/triggers/
sudo tail -40 /Users/operator/.local/state/<hostname>-transmission-trigger-watcher.log
- A file named only with a hash is waiting. A
<hash>.retry.<n>file counts failed attempts. A<hash>.deadfile was given up. macOS path does not existin the watcher log means the NAS is not mounted.Done script failed for:lines name the download. The reason is in~/.local/state/transmission-processing.logof theoperatoraccount.
Fix
-
If the watcher is not running, restart it:
-
If the NAS is not mounted, fix the mount. See Plex libraries are empty or files show as unavailable.
-
Fix the cause in
transmission-processing.log. Then rename the dead trigger back to its hash, and the watcher picks it up within 60 seconds:
A download went to triage instead of the library¶
Cause
transmission-done moves a download to a folder under Media/Torrents/triage/ when it cannot place it:
already-in-plex/: FileBot matched it, but the library already has that file. Media-compare has handled it, and no email is sent.no-match/: FileBot could not identify it, or the year guard refused a movie match because the year in the release name is not the year of the match.failed/: another error, for example a network, license or permission problem.
Check
sudo -iu operator ls "/Users/operator/.local/mnt/<share>/Media/Torrents/triage/no-match" \
"/Users/operator/.local/mnt/<share>/Media/Torrents/triage/failed"
sudo grep -E 'YEAR MISMATCH|LICENSE|triage|Error' /Users/operator/.local/state/transmission-processing.log | tail -30
YEAR MISMATCH: lines show a refused movie match. LICENSE lines show a FileBot license problem. The lines before each triage line show FileBot's output for that download.
Fix
- For a year mismatch where the match was correct, rename the file or folder so that its year matches the database, then process it by hand.
- For a name that FileBot cannot read, rename it to a clear
Title (Year)orShow S01E01form, then process it by hand. -
To process a folder by hand, run
transmission-donewith noTR_TORRENT_*variables in Terminal in theoperatordesktop session. It starts in manual mode and asks for the folder: -
For
failed/, fix the cause first. See the license and permission sections below.
No email arrives for a download that could not be processed¶
Cause
transmission-done emails alerts.email from its config.yml for each download that it moves to no-match/ or failed/. If the key is missing, or the alert library is missing, it triages the download and logs that it sent no email. A config.yml written before this feature has no alerts.email until setup runs again.
Check
sudo -iu operator yq eval '.alerts.email' /Users/operator/.config/transmission-done/config.yml
sudo grep 'No alerts.email in config' /Users/operator/.local/state/transmission-processing.log | tail -5
null means the key is missing.
Fix
- Run
transmission-filebot-setup.shagain. It writesalerts.emailfromMONITORING_EMAIL. -
Or add the key by hand to
/Users/operator/.config/transmission-done/config.yml: -
If email still does not arrive, check msmtp. See Monitoring.
FileBot reports a license problem¶
Cause
FileBot needs a license for automated use. The license file was not installed, or it expired.
Check
sudo -iu operator filebot --license
sudo grep -A4 'LICENSE' /Users/operator/.local/state/transmission-processing.log | tail -10
Fix
- Install the license file for
operator.prep-airdrop.shadds it to the package whenFILEBOT_LICENSE_FILEis set, andfilebot-setup.shinstalls it. - Run
filebot-setup.sh --license-file <path>again with the license file. - Process the downloads in
triage/failed/by hand.
FileBot fails with Access Denied or I/O errors on the NAS¶
Cause
The NAS refuses the write. NFS checks permissions on the NAS, not on the Mac. The NFS export must map all users to the NAS admin user, and the media folders must be writable by that user. A [MOVE] ... failed due to I/O error line or an Access Denied line with a permission string points here.
Check
sudo grep -E 'Access Denied|I/O error|Permission denied' /Users/operator/.local/state/transmission-processing.log | tail -10
Fix
- Check the NFS rule of the shared folder on the NAS: read and write, map all users to admin, non-privileged ports allowed, subfolder access allowed.
- Fix folder permissions on the NAS itself, over SSH to the NAS. A
chmodfrom the Mac does not work on this mount. - See NAS storage configuration.
transmission-done has been running for over 45 minutes¶
Cause
Normal runs take seconds to a few minutes. A long run usually waits for a macOS privacy prompt "bash would like to access files on a network volume". macOS holds the first non-Apple binary in the chain responsible for FileBot's reads. The watcher puts the stably-signed bash at /usr/local/stable/bash/bin first so that the grant survives brew upgrade. stall-watchdog emails transmission-done has been running for over 45 minutes.
Check
ps -axo pid=,etime=,command= | grep '[t]ransmission-done'
/usr/local/bin/<hostname>-stable-sign.sh --check
The second column is the elapsed time. --check exits 1 if the stable bash copy is stale.
Fix
- Look at the desktop for a privacy prompt, and click Allow.
- Do not kill
transmission-done. Stopping FileBot during a move can lose the file. - If the stable copy is stale, run
/usr/local/bin/<hostname>-stable-sign.sh.
See Stable signing.
A download was deleted from pending-move before it was processed¶
Cause
pending-move-cleanup.sh runs every hour. It removes entries in pending-move/ whose names Transmission no longer lists. An earlier version compared names without removing the .part suffix that single-file downloads have while they are written, so it could delete a download in progress. The current template removes the suffix before it compares, but the deployed copy at ~operator/.local/bin/pending-move-cleanup.sh changes only when you deploy again.
Check
sudo tail -30 /Users/operator/.local/state/<hostname>-pending-move-cleanup.log
sudo grep -c '%.part' /Users/operator/.local/bin/pending-move-cleanup.sh
Removing orphaned entry: lines name what the script removed. Left in place: lines name entries that it kept because only .nfs.* files remain. A count of 0 from the second command means the deployed script is older than the fix.
Fix
- Run
podman-transmission-setup.shagain to deploy the current cleanup script. - A file that was deleted while a process still had it open may survive as a hidden
.nfs.*file inpending-move/. The NFS client keeps a deleted, open file under that name. This recovery is not automated, and it works only while the file is still open. Compare its size with the torrent's size before you use it. - If the sizes match, move it back to the torrent's real name in
pending-move/, and rename the torrent's.deadtrigger back to its hash, as in A finished download is not processed.
Old folders build up in pending-move¶
Cause
The cleanup skips a cycle when it cannot reach the Transmission RPC. It also keeps folders that Transmission still lists, and folders that hold only .nfs.* files.
Check
sudo launchctl print gui/$(id -u operator)/com.<hostname>.pending-move-cleanup | grep -E 'state|last exit|run interval'
sudo grep -E 'Cleanup complete|Cannot reach' /Users/operator/.local/state/<hostname>-pending-move-cleanup.log | tail -5
Cleanup complete: gives the counts of removed, tracked, held and failed entries. Cannot reach Transmission RPC means Transmission was down. See Transmission web UI does not load.
Fix
- Make sure that Transmission answers.
- Folders that hold only
.nfs.*files clear after VirtioFS releases the files, which can take hours. The cleanup removes them on a later run.
Catch finds new episodes but Transmission does not add them¶
Cause
- Catch is not running. Its LaunchAgent starts it at login and does not restart it.
- Catch has no feed.
catch-setup.shadds a feed only whenCATCH_FEEDS_URLis set. - A magnet link reached
TransmissionMagnetHandler.app, but the Transmission RPC did not answer. The handler shows the notificationCould not connect to Transmission.
Check
pgrep -fl Catch.app
sudo launchctl print gui/$(id -u operator)/com.<hostname>.catch | grep -E 'state|last exit'
sudo -iu operator defaults read org.giorgiocalderolla.Catch feeds
No process means Catch is not running. An empty feed list means no feed is set.
Fix
-
Start Catch by hand in the
operatorsession, or restart its agent: -
Set
CATCH_FEEDS_URLinconfig.confand runcatch-setup.shagain. - If the handler cannot reach Transmission, fix Transmission first. See Transmission web UI does not load.