Skip to content

jackson2w/claude-code-skills / jellyfin-media-permissions

jellyfin-media-permissions

Verified

This skill should be used when Jellyfin shows "Playback failed due to a fatal player error" for a newly-added title, when a library item has empty/stub metadata (title from the folder name only, no overview/poster/runtime), or when media was ingested via an rsync pipeline from macOS. Trigger phrases include "fatal player error", "jellyfin playback failed", "jellyfin permission denied", "jellyfin metadata empty", "openrsync chown", "rsync macOS uid gid Linux permissions".

Jellyfin media permission/metadata troubleshooting

Covers a specific, reproducible failure mode: media lands on disk via some sync pipeline (rsync, scp, etc.), Jellyfin's library scan picks up the filename fine, but the file is unreadable by the Jellyfin service account — surfacing as a playback error and/or a stub library entry with no real metadata. First hit 2026-07-17 debugging a movie synced in over the Jellyfin dropbox-sync pipeline (see the homelab project's own memory for that pipeline's specifics); the underlying mechanism generalizes to any media-server-behind-a-sync-job setup.

The macOS rsync root cause

macOS's built-in rsync is openrsync (protocol 29), not classic GPL rsync — check with rsync --version. It has no --chown, --no-owner, or --no-group flags. -a (archive) still preserves the local macOS account's uid/gid and file mode verbatim onto the remote side. If the source file has a restrictive mode (600, owner-only — common for browser downloads, which often carry a quarantine xattr too) and the remote consumer runs as a different service account (e.g. jellyfin, not the account that owns the transferred bytes), that account can't read it. This is silent on the sync side — rsync exits 0, the transfer looks completely successful — and only manifests as an error on the Jellyfin side, often much later when someone tries to play the file.

Because there's no rsync flag to fix this from the macOS end, fix it with a post-transfer remote command instead, folded into whatever script does the sync:

ssh "$REMOTE" "chown -R jellyfin:jellyfin /path/to/media && \
    find /path/to/media -type d -exec chmod 755 {} + && \
    find /path/to/media -type f -exec chmod 644 {} +"

Don't try to reshape the rsync invocation to work around this (e.g. stripping -a down to -rlptD still leaves ownership ambiguous depending on how the receiving process is invoked) — a dedicated fixup step after the transfer is simpler and unambiguous.

Diagnosing: two things break together, not just playback

A permission-denied file blocks both:

  1. Playback — the transcoder (or direct-play file read) can't open the file. This is what surfaces to the user as "Playback failed due to a fatal player error."
  2. Metadata identification — Jellyfin's probe step (ffprobe-equivalent, needed to get runtime/codec info) fails for the same reason, which can abort the rest of that item's scan before it reaches online provider lookup (TMDb/etc.) or before it can write .nfo/extracted images back into the media folder (needs the directory to be writable by jellyfin, not just the file to be readable — check both, they can differ, e.g. 755 on the parent dir has no write bit for anyone but the owner).

Diagnostic signature in the library: an item whose Overview/Genres are empty and whose runtime is null, with Name/ProductionYear that look exactly like a straight parse of the folder name — that's the fingerprint of the scan erroring out before it got to identification, not a genuine "no provider match" (a real failed match still completes the probe, so runtime would be populated). Query directly if the Jellyfin API/dashboard isn't handy:

# sqlite3 CLI often isn't installed on a minimal Debian LXC — python3's stdlib module works fine:
python3 -c "
import sqlite3
c = sqlite3.connect('/var/lib/jellyfin/data/jellyfin.db').cursor()
c.execute(\"SELECT Name, ProductionYear, Overview, RunTimeTicks, Path FROM BaseItems WHERE Name LIKE '%<title fragment>%'\")
for row in c.fetchall(): print(row)
"

Confirm the actual cause (don't guess from ls -la alone — that shows a permission, not whether the specific service account can use it) by testing as the real service user:

sudo -u jellyfin test -r /path/to/file.mkv && echo READABLE || echo NOT_READABLE
sudo -u jellyfin touch /path/to/parent-dir/.write-test && echo WRITABLE

Also check journalctl -u jellyfin for the literal Permission denied line from the jellyfin binary itself (distinct from its own [ERR] log lines) plus Error in Probe Provider / Error in metadata saver / UnauthorizedAccessException ... .nfo — these three together are the fingerprint of this exact failure, not a codec/container problem.

Rule out a real media problem first

Before assuming permissions, a quick ffprobe as root (root bypasses file permission checks entirely, so this works even on a file the jellyfin user can't read yet) confirms whether the file itself is fine:

/usr/lib/jellyfin-ffmpeg/ffprobe -v error -show_entries stream=index,codec_type,codec_name -of default=noprint_wrappers=0 /path/to/file.mkv

Plain H.264/HEVC/VP9 video + AAC/AC3/etc. audio is fine for Jellyfin's default transcoder. If there's an extra video stream, check its disposition — a cover-art thumbnail should show DISPOSITION:attached_pic=1 and DISPOSITION:default=0; if so it's correctly excluded from playback stream selection and isn't the problem.

After fixing permissions

Playback works on the very next attempt with no further action — probing happens live at playback time. The library metadata does not self-heal though; Jellyfin doesn't automatically retry a previously-failed identify pass. Trigger it manually: on the item, "⋮" → Refresh Metadata → Replace All Metadata and Images (or Scan All Libraries for the whole library). Verify the fix actually took by re-running the same sudo -u jellyfin read/write test above, not just by re-checking ls -la permission bits.

Separate gotcha this can uncover: if metadata refresh still comes back with no real overview/poster after permissions are confirmed fixed, that's a provider (TMDb) title-match miss, not a permissions problem — e.g. a folder name that drops punctuation from a person's billed name (Louis CK vs. the actual Louis C.K.) can fail online lookup outright. Fix via Jellyfin's own "Identify" search on that item (search by a corrected title or a known provider ID) rather than re-chasing permissions.

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall