Setup Health

Back to Guides · Configuration & API Reference · Multi-Media-Server Guide

The Setup Health tab of Servers → Edit is the single place to verify — and adjust — every server-side setting that affects whether this app's previews show up in Plex / Emby / Jellyfin.

The checks are grouped by what needs your attention:

1. Must fix — a critical check is failing.
2. Recommended — the server works, but a setting could be better. Apply recommended changes it; a row that the app can't change shows a Manual chip.
3. All good — checks that pass.

Fix critical and Fix all apply several fixes at once, after a preview of the changes. Each check covers one of these areas: connection and version, plugin presence, per-library (or server-wide for Plex) flags, server trickplay geometry, vendor extraction, path mappings and Plex config folder writability.

A server with Intro & Credits switched on also gets an Intro & Credits section (Plex) or plugin rows (Jellyfin, Emby). A Plex server with Generate chapter thumbnails switched on also gets a Chapter thumbnails section. A Plex server with this app's loudness analysis switched on also gets a Plex loudness section.

Every row carries an ⓘ tooltip (the one-liner), a direct link to this page anchored at the relevant check, and — where applicable — an Enable or Disable toggle that applies immediately.

Connection

What it checks: the configured URL + credentials reach the media server and return an identity response (Plex machineIdentifier, Emby/Jellyfin /System/Info).

Why it matters: every other check depends on this working. A red row here almost always means the URL is wrong, the credential expired, or the container can't see the server.

Enable / disable: read-only check — fix the URL or credential in the server's Configure dialog.

Verify: re-open Configure and click the refresh icon next to the badge.

Server version

What it checks: Jellyfin must be 10.10 or newer; Plex and Emby are informational for scrubber previews (any recent release works). Optional Plex chapter registration has a separate version check and currently supports 1.43.4.x or 1.43.5.x.

Why it matters: pre-10.10 Jellyfin ignores the SaveTrickplayWithMedia flag and looks for trickplay under <config>/data/trickplay/, which this app never writes to. Upgrade is the only fix.

Enable / disable: read-only — upgrade via your container / package manager.

Chapter thumbnails

Plex only — shown when Generate chapter thumbnails is on

Registration: checks that this app can safely update the image references on Plex's existing chapters. It requires a supported Plex version and database schema, a positive server identity match, and a writer on Plex's machine. A safe local database connection works directly; when Plex is on another machine, pick a compatible Plex database node beside it. A network-mounted database alone is not enough.

The failure row gives the reason. Choose the Plex database opens the Plex database selector under Edit → Connection; you can pick a node while Intro & Credits stays off. See Plex on another machine. This check reads capability only and does not change chapter rows.

Plex's own generation: reads the server-wide Generate chapter thumbnails preference (GenerateChapterThumbBehavior). Never avoids duplicate native work and lets this app supply the images. Both As a scheduled task and As a scheduled task and when media is added can make Plex regenerate and replace them. Change this manually in Plex Settings → Library; it affects all Plex libraries. The app does not change it when saving its own toggle. If the preference cannot be read or has an unknown value, the check says Unable to verify rather than reporting success. Never disables automatic native chapter generation, but it does not stop Plex's ordinary file checks from rewriting chapter image references. A later Previews job can reconcile those references without decoding current images. That does not clear Plex's image cache: clients can continue showing older images after regeneration, including when Plex generates the replacements itself. See the cache limitation.

Turning this app's chapter option off removes these checks and preserves previously generated images. See Plex chapter thumbnails for job behavior.

Plex loudness

Plex only — shown when this app's loudness analysis is on

Writer readiness: checks that this app can safely store loudness measurements in Plex's database. Select the movie and TV libraries this app should analyse in the server's loudness settings.

Plex's own analysis: recommends setting the server-wide Analyze audio tracks for loudness schedule to Never. While it's on, Plex analyses the same videos this app does, on the Plex machine's CPU. Keep it on, and dismiss the recommendation, if you need it for music, unselected video libraries or excluded files.

Set to Never: available when this app's writer is ready and eligible video libraries are selected. The confirmation explains that it stops Plex's native loudness analysis in every library, including music. It does not turn on this app or expand its coverage, and existing measurements remain available. Selection and writer readiness are checked again before the change is sent to Plex. This action is excluded from bulk fixes.

Installing or upgrading this app does not change Plex's loudness schedule. See Plex loudness analysis for the supported libraries and job behavior.

Media Preview Bridge plugin

Jellyfin only

What it checks: the Media Preview Bridge plugin responds on GET /MediaPreviewBridge/Ping.

Why it matters: with the plugin, new previews become visible to Jellyfin instantly (Mode A). Without it, previews are adopted on the next library scan or Jellyfin's daily 3 AM task (Mode B) — still works, just slower to appear.

Enable: one-click Install plugin. The app adds its manifest URL to Jellyfin's plugin repos, queues the install, and restarts Jellyfin. Takes ~30 s; the Setup Health card polls until the plugin is live.

Disable: Uninstall plugin (with confirm). Removes the package and restarts Jellyfin. Published tiles stay on disk and are re-discovered by the next library scan — no data loss.

Library settings

Per-library (or server-wide for Plex) flags governing preview generation, scan behaviour, and trickplay adoption.

Trickplay enabled (EnableTrickplayImageExtraction)

Jellyfin only

What it checks: Jellyfin's master trickplay gate on each library.

Why it matters: off makes Jellyfin delete the .trickplay/ directory this app published on the next library refresh (TrickplayManager.RefreshTrickplayDataInternal prunes what it considers orphaned data). This is the most destructive flag in the system.

Enable: one-click Enable. Flips the flag to true for this library.

Disable: requires typing disable trickplay to confirm. Do not click through the dialog — Jellyfin will delete every preview tile this app has generated for the library. You'll need to re-run the generator to restore them.

Save trickplay with media (SaveTrickplayWithMedia)

Jellyfin only

What it checks: that Jellyfin looks for trickplay where this app writes it. The recommended value depends on the server's Store trickplay off the media drive setting:

• Off (default): recommend on — Jellyfin reads from <media>.trickplay/, where the app writes beside each video.
• On (off-media): recommend off — Jellyfin reads from <config>/data/trickplay/, the data folder the app writes into.

Why it matters: a mismatch means published tiles sit on disk but are invisible to Jellyfin. Files aren't deleted — just unreachable until the flag matches the layout the app is writing.

Enable / disable: toggle via the inline Enable / Disable buttons. Disable shows a click-to-confirm dialog (non-destructive but breaks visibility).

Store trickplay off the media drive (off-media)

Jellyfin only — shown when the server's "Store trickplay off the media drive" toggle is on

What it is: instead of writing trickplay next to each video, the app writes it into Jellyfin's data folder (<config>/data/trickplay/<id[:2]>/<id>/<width> - 10x10/), exactly like Plex keeps its previews. This keeps the media drive clean and works even when the media is mounted read-only.

What it checks: that the Jellyfin config folder you set is mounted into this container read-write. It's a pure read-only probe — os.access(W_OK) only, no test write. States: writable (good), missing (path not mounted here), read-only (mounted :ro or wrong PUID/PGID), unset (no folder configured).

Requirements (all three):

1. The Media Preview Bridge plugin installed in Jellyfin (it's the only thing that registers off-media tiles with the correct thumbnail count). The plugin section becomes a hard requirement when off-media is on.
2. Jellyfin's config dir bind-mounted read-write into this container, with the Jellyfin config folder field pointing at that mount.
3. SaveTrickplayWithMedia off for the libraries (Setup Health flips the recommendation for you).

How to fix: set the mount in your Docker config (e.g. -v /path/to/jellyfin/config:/jellyfin-config, not :ro) and enter that container path in the server's Jellyfin config folder field.

Scan-time extraction (ExtractTrickplayImagesDuringLibraryScan)

Jellyfin + Emby

What it checks: vendor's scan-time trickplay generation flag.

Why it matters:

• With the Media Preview Bridge plugin installed (Mode A): recommend off. The plugin registers previews directly; scan-time extraction is wasted CPU.
• Plugin absent (Mode B): recommend on. Jellyfin's TrickplayProvider only adopts existing tiles on scan when this flag is on. Off without the plugin means adoption stalls until the 3 AM daily task.
• Emby: recommend off. Emby has no plugin mode; its scan-time extraction just repeats this app's work.

Enable / disable: toggle directly. Disable while in Mode B shows a click-to-confirm dialog.

Chapter-image extraction (ExtractChapterImagesDuringLibraryScan)

Emby only

What it checks: Emby's older preview pipeline that predates trickplay.

Why it matters: when this app owns trickplay, chapter-image extraction is wasted CPU. Disabling it doesn't affect anything this app publishes.

Enable / disable: toggle directly. Non-destructive either way.

Real-time monitor (EnableRealtimeMonitor)

Emby + Jellyfin

What it checks: vendor's filesystem watcher that auto-detects new files without waiting for a manual scan.

Why it matters: off means Sonarr/Radarr imports only get noticed on the next manual scan or webhook nudge — the "not in library yet" state hangs around longer than necessary.

Enable / disable: toggle directly. Non-destructive either way.

FSEvent library updates (FSEventLibraryUpdatesEnabled)

Plex only — server-wide

What it checks: Plex's filesystem event subscription in Settings → Library.

Why it matters: off = Plex never reacts to filesystem changes. Your only signals for new files become this app's scan-nudges (at most one per folder a minute) and Plex's periodic timer. Most "why didn't Plex pick up the file?" complaints trace back here.

Enable / disable: toggle directly. Server-wide setting (not per-library).

FSEvent partial scan (FSEventLibraryPartialScanEnabled)

Plex only — server-wide

What it checks: when on, Plex only re-scans the directory that changed; off = full library scan per added file.

Why it matters: off can turn a single-episode import into a multi-minute full scan.

Enable / disable: toggle directly.

Scheduled library updates (ScheduledLibraryUpdatesEnabled)

Plex only — server-wide

What it checks: Plex's periodic-scan safety net.

Why it matters: belt-and-braces in case the real-time watcher misses an event (network mounts, container restarts). Default 12 h interval is fine.

Enable / disable: toggle directly.

Server trickplay options

Jellyfin only

What it checks: server-wide TrickplayOptions (tile width, tile height, interval, resolution widths) match this app's adapter geometry.

Why it matters: Jellyfin synthesises the client-facing TrickplayInfo row from server-wide TrickplayOptions verbatim — not measured from the tiles themselves. A mismatch (e.g. server TileWidth=8 vs adapter 10) makes the scrubber pull the wrong pixel range per tile. Previews appear to load but render wrong.

Enable: Sync options — fetches the server config, rewrites only TileWidth, TileHeight, Interval, and ensures the adapter's width is listed first in WidthResolutions, then POSTs back.

Disable: no disable — syncing is idempotent.

Vendor-side preview generation

What it checks: whether the vendor is generating its own previews on top of this app's output.

Why it matters: with this app owning previews, vendor-side generation is wasted CPU. Plex: enableBIFGeneration per library section. Emby: ExtractTrickplayImagesDuringLibraryScan + ExtractChapterImagesDuringLibraryScan per library. Jellyfin: ExtractTrickplayImagesDuringLibraryScan, while EnableTrickplayImageExtraction stays on (destructive when off — see above). For Jellyfin this row follows the same plugin rule as scan-time extraction: with the plugin installed it recommends "stopped" and offers Disable; without the plugin it recommends "running" and offers only Enable, because Jellyfin then picks up this app's tiles through that scan.

Enable / disable: toggles with the current aggregate state reported (e.g. "stopped on 3/5 libraries"). Non-destructive.

Plex config folder

Plex only

What it checks: the configured Plex data folder exists on this container and is writable. The app probes os.access(folder, W_OK) only — no test write, no tempfile, no chmod.

Why it matters: BIF bundles land under Media/localhost/<hash>/ inside this folder. A :ro Docker mount, a wrong path, or a PUID/PGID mismatch silently blocks every publish.

Enable / disable: read-only status row. Fix the mount or the path in the server's Configure dialog.

Path mappings

What it checks: every configured local_prefix exists on this container.

Why it matters: if a local_prefix is missing, the mapping effectively no-ops — scan-nudges go out with unmapped paths and publishing fails silently.

Enable / disable: read-only status row. Fix under Servers → Edit → Path mappings.

Intro & Credits

These rows appear only for a server that has Send intro & credits markers to this server switched on (Servers → Configure → Processing → Intro & Credits). Until then the server shows one row, Intro & Credits is off for this server, under "All good", and nothing about markers is checked or contacted. The rows are read from the same check the Processing → Intro & Credits section runs, so the two never disagree. A fact the check never got to read shows no row: a Plex whose database is on another machine says nothing about Plex Pass until that is fixed.

Only Plex's library-settings and detection rows have buttons (Turn on, Set server-wide to Never). Every other row says what to change and where.

Plex

• Skip buttons need Plex Pass (critical) / Plex Pass is active. Without Plex Pass Plex serves no intro or credits markers at all, not ours and not its own, so nobody sees a skip button, and this app writes nothing to it until the server has a Pass. Viewers need Plex Pass or to be in your Plex Home too.
• Plex hasn't made its marker list yet (critical) / Plex's marker list is ready. Plex only serves markers attached to a database row it made itself, and this app never creates that row. Turn on Plex's own intro detection for one library, play a file, then check again. Afterwards you can set Plex's server-wide detection back to Never; leave the library's own setting on.
• Plex's library database isn't on this machine (critical) / …is on this machine. Markers are written into Plex's database, which is only safe from the machine the file is on. Run this app on the Plex machine, or run the Plex database node next to Plex. With a node picked the row reads The Plex database node isn't on the machine with Plex's database, and its badge reads Fix on the node: give the node Plex's config folder from one of that machine's own disks.
• The Plex database node (critical), shown only when a node is picked for this server. …is connected, or one of: isn't answering (markers wait, nothing is lost), refused this app's key (set the same key on the node and on the Nodes page), and this app are different versions (the message says which to update), is beside a different Plex (check the address: markers would have gone into the wrong database). While it is red, no marker reaches this server, and its badge reads Fix on the node instead of Change in Plex UI. A node that is turned off on the Nodes page, or that no longer exists, reads Fix in this app.
• TV Shows — skip buttons are hidden (critical, one row per library, named after it) / Plex shows skip buttons in your Intro & Credits libraries. Each library Intro & Credits goes to has its own Intro markers and Credits markers setting in Plex (Edit library → Advanced; only TV libraries have the intro one). While one is off, Plex hides every marker of that type in the library, its own and ours, so nobody sees a skip button there. Until it is back on, the app doesn't use any of Plex's own markers on that library's items as a second opinion, of either type. The row names the settings that are off, and Turn on switches them back on for that library, after a confirmation. Fix critical turns them all on after showing the list.
  • Under the last such row, a note offers Set server-wide to Never: it sets Plex's server-wide Generate intro video markers / Generate credits video markers (Settings → Library) to Never for the types that are off. That stops Plex's own detection and keeps skip buttons working. It isn't offered when Plex already never detects them, or when the server is set to "Keep Plex's".
  • A setting that can't be read (an older Plex, or Plex didn't answer) shows no row.
• Plex's own detection can replace your markers (recommended). When Plex analyses a file again it replaces the markers on it with its own, ours included. The next Intro & Credits run puts ours back, but the file shows Plex's times until then. Set server-wide to Never sets Plex's Generate intro video markers / Generate credits video markers to Never for the types Plex detects in your Intro & Credits libraries, after a confirmation. It changes every library on the server, so Fix all leaves it out.
  • Plex's own detection is off / …doesn't reach your Intro & Credits libraries: nothing to do.
  • Keeping Plex's own markers: its detection can stay on: the server is set to "Keep Plex's" under "When Plex has its own markers", so Plex's detection is what you asked for.

Jellyfin and Emby

• Media Preview Bridge plugin (Jellyfin) and Media Preview Bridge for Emby plugin (Emby), critical. Neither server has an API for markers, so the plugin is the only way they reach it. Previews are not affected. The row offers Install where the app can do it; on an Emby whose plugin catalogue doesn't list the plugin (or whose catalogue couldn't be read) it says to install it by hand and the Processing → Intro & Credits section links the guide. Emby and Jellyfin restart once.
• The plugin is too old for intro and credits markers (recommended). The installed build works for previews but doesn't answer the markers feature, so markers wait. Update the plugin; nothing already published is lost.

Troubleshooting

• Card says "ready (next scan)" and I want "ready (instant)": install the Media Preview Bridge plugin (Jellyfin only).
• Card flickers between states after a fix: normal during Jellyfin restart (up to ~30 s). The card polls until the server stabilises.
• "action needed" badge persists after fixing a flag: click the refresh icon next to the badge — the probe caches for the duration of the modal open.
• A disable toggle is greyed out: that flag is already disabled. The UI only shows the toggle that would actually change state.

Related

• Multi-Media-Server Guide — webhook routing, per-server path mappings
• FAQ
• Configuration & API Reference — API endpoint schemas including /previews-readiness, /health-check/apply, /install-plugin, /uninstall-plugin