---
title: Setup Health
heading: Setup Health
description: What each Setup Health check means and how to fix it, so Plex, Emby and Jellyfin show the preview thumbnails
  this app generates.
---

> [Back to Guides](../guides.md) · [Configuration & API Reference](../reference.md) · [Multi-Media-Server Guide](../multi-server.md)

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](#intro-credits) (Plex) or plugin rows (Jellyfin, Emby).
A Plex server with **Generate chapter thumbnails** switched on also gets a
[Chapter thumbnails section](#chapter-thumbnails).
A Plex server with this app's loudness analysis switched on also gets a
[Plex loudness section](#plex-loudness).

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.

> [!WARNING]
> A handful of toggles are **data-destructive**. The UI surfaces a
> typed-confirmation dialog for those cases. The danger is real: flipping
> `EnableTrickplayImageExtraction` off makes Jellyfin delete the
> `.trickplay/` directory this app published on its next library
> refresh. Read the section below before clicking.

---

## Connection  <a id="connection"></a>

**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  <a id="version"></a>

**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  <a id="chapter-thumbnails"></a>
*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](../guides.md#plex-on-another-machine-the-plex-database-node).
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](../guides.md#plex-chapter-thumbnails).

Turning this app's chapter option off removes these checks and preserves previously generated images.
See [Plex chapter thumbnails](../guides.md#plex-chapter-thumbnails) for job behavior.

---

## Plex loudness  <a id="plex-loudness"></a>
*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](../plex-loudness-normalization.md) for the supported libraries and job behavior.

---

## Media Preview Bridge plugin  <a id="plugin"></a>
*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  <a id="library-settings"></a>

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

### Trickplay enabled (EnableTrickplayImageExtraction)  <a id="enable-trickplay"></a>
*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)  <a id="save-trickplay-with-media"></a>
*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)  <a id="jellyfin-config-folder"></a>
*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)  <a id="scan-extraction"></a>
*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)  <a id="chapter-extraction"></a>
*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)  <a id="realtime-monitor"></a>
*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)  <a id="fsevent-updates"></a>
*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)  <a id="fsevent-partial"></a>
*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)  <a id="scheduled-scan"></a>
*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  <a id="trickplay-options"></a>
*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  <a id="vendor-extraction"></a>

**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](#scan-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  <a id="plex-config-folder"></a>
*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  <a id="path-mappings"></a>

**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  <a id="intro-credits"></a>

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](../guides.md#plex-on-another-machine-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](../multi-server.md) — webhook routing,
  per-server path mappings
- [FAQ](../faq.md)
- [Configuration & API Reference](../reference.md) — API endpoint
  schemas including `/previews-readiness`, `/health-check/apply`,
  `/install-plugin`, `/uninstall-plugin`