Troubleshooting

Plugin becomes unreachable (HTTP 500) after an update

A simple Jellyfin restart may not be enough after updating the plugin. Do a full restart of the Jellyfin process itself (for example docker restart <container>) to clear the File Transformation plugin's static state.

JellyUX sections don't appear on Jellyfin Media Player (Windows)

Jellyfin Media Player keeps an internal auto-connect cache (userWebClient in %LOCALAPPDATA%\JellyfinMediaPlayer\jellyfinmediaplayer.conf, main section) that isn't invalidated when you switch servers in the app. It keeps loading the web client, so every plugin (not just JellyUX), from the previously connected server, regardless of which server is currently selected.

Recommended fix: in the app's settings, use the Reset Saved Server button (shown automatically whenever a server is cached).

Fallback: edit jellyfinmediaplayer.conf and reset userWebClient to an empty string. Don't confuse this with the %LOCALAPPDATA%\Jellyfin Media Player cache folder (with spaces): clearing that one does not fix this specific issue, since it's an auto-connect cache, not a browser cache.

This is unrelated to JellyUX. ZestyTheme's theme.css intentionally hides .btnForgotPassword on the login page. To use password recovery, temporarily disable the ZestyTheme custom CSS (or remove the button's display: none override locally), recover the password, then re-enable the theme.

If an external widget pack (a third-party DLL dropped into the plugin's widget-packs folder) fails to load, a warning banner appears at the top of the admin configuration page listing the failed file(s) and the reason. The rest of the plugin, including all built-in widgets, keeps working normally. Check the failure reason in the banner (or in the Jellyfin server logs) to determine whether the pack targets an incompatible plugin version, or is otherwise malformed.

TMDb requests stop working after a network outage

Connected widgets rely on TMDb's public API. After 3 consecutive network-level failures (not an invalid API key, which is reported separately), a circuit breaker opens and TMDb requests are skipped for 5 minutes rather than retried on every widget load. Look for a log line similar to:

TMDb circuit breaker opened after 3 consecutive failures; TMDb requests will be skipped for 5 minute(s).

This is expected behavior during a sustained TMDb outage and requires no action: normal requests resume automatically once the 5-minute window elapses and TMDb is reachable again.

Sections don't appear even after clearing the browser cache and using incognito mode

If the home page still shows native Jellyfin sections after installing or updating JellyUX, and this persists even in a private/incognito window or after fully clearing browser data, the cause is probably not the browser at all: a CDN or a caching reverse proxy in front of your Jellyfin server may be serving a cached copy of the patched chunk from before the install/update.

This was confirmed on a real deployment (TrueNAS app, Jellyfin behind an nginx reverse proxy, DNS managed through Cloudflare): the chunk containing loadSections was served with cf-cache-status: HIT at Cloudflare's edge, from before the plugin was installed. No amount of browser-side cache clearing can bust an edge/CDN cache, since it lives entirely outside the browser.

How to check: open your browser's developer tools (F12), go to the Network tab, reload the home page, find the request for the *.chunk.js file containing your home screen bundle, and inspect its response headers. A cf-cache-status: HIT (Cloudflare) or similar cache-hit header from any other CDN/reverse proxy confirms this is the cause rather than a plugin issue.

Fix: purge the cache at the CDN/proxy level, not the browser: - Cloudflare: dashboard > your zone > Caching > Configuration > Purge Cache (Purge Everything is simplest, since the chunk's filename hash changes on every Jellyfin Web update anyway). - nginx reverse proxy with proxy_cache: clear the configured cache path, or reload nginx if it was configured to bypass its own cache for the relevant location. - Other CDNs: use their equivalent cache purge/invalidation feature.

If you consistently run into this after every JellyUX update, consider adding a cache rule at your CDN/proxy that bypasses caching for *.chunk.js/*.bundle.js paths, or that purges automatically as part of your plugin update routine.

Home page falls back to native rendering after a Jellyfin update

JellyUX patches a specific Jellyfin Web chunk to render its widgets. If Jellyfin Web's internal bundle changes shape (a "drift"), the patch may no longer apply, and a warning appears in the server logs:

Chunk <file>.chunk.js contains ',loadSections:' but the minified hook could not be resolved.

If you see this line, the home page falls back to Jellyfin's native rendering rather than showing a broken page. This is a known limitation of patching a third-party bundle that isn't part of JellyUX's public API. Check the project's GitHub Issues for a compatibility update, or open a new issue if none exists yet.