Troubleshooting

Symptom-first. Scan the headings for what you're seeing, follow the steps in order.

Plugin disappears after restart ("tombstoned")

Symptom: Plugin appears in the list for a second, then vanishes. Jellyfin log shows NotSupportedException or FileNotFoundException for a DLL like FFMpegCore, CliWrap, Instances, or SixLabors.ImageSharp.

Cause: dotnet build only emits the main plugin DLL — transitive NuGet dependencies must ship inside the ZIP alongside it.

Fix:

1. Verify the plugin folder contains all DLLs shipped in the official release ZIP (~15 files, not just one).
2. If you built from source, use dotnet publish -c Release and ship the full bin/Release/net9.0/publish contents.
3. Re-enable via REST: POST /Plugins/{id}/{version}/Enable with an admin X-Emby-Token.
4. Restart Jellyfin. The plugin should stay loaded.

Ffprobe/FFmpeg: "Cannot start process because a file name has not been provided"

Symptom: Scheduled task fails at 0% with InvalidOperationException: Cannot start process because a file name has not been provided.

Cause: Pre-v1.6.1.16 plugins captured MediaEncoder.EncoderPath/ProbePath at construction time. If the plugin was constructed before Jellyfin finished resolving these paths, the capture was an empty string — permanently.

Fix: Upgrade to v1.6.1.16+. The fix applies to all three singletons (VideoAnalyzer, VideoFrameProcessor, ProcessingMethodExecutor) and late-resolves on every entry point.

AI service test connection fails

Symptom: The Test Connection button in plugin config shows red.

1. Check the URL: it must be reachable from the Jellyfin container, not from your browser. If Jellyfin runs in Docker, localhost means the Jellyfin container — use the LAN IP or Docker service name.
2. Check the token: if API_TOKEN is set on the AI container, the plugin must send the same value. Mismatched token → 401.
3. Check that port 5000 is exposed: curl -f http://ai-host:5000/health from the Jellyfin host.
4. CORS / proxy: if there's a reverse proxy in front, it must not strip the X-Api-Token header.

GPU not detected in the service

Symptom: /hardware shows only CPU providers, or the dashboard "Detected Hardware" row is empty.

• NVIDIA: container must have runtime: nvidia (compose) or --gpus all (docker run). Run docker exec ai-upscaler nvidia-smi — if this fails, the NVIDIA Container Toolkit isn't installed on the host.
• Intel (OpenVINO): container needs --device /dev/dri. On Unraid, the Intel GPU Plugin must be installed.
• AMD (ROCm): needs --device /dev/kfd and --device /dev/dri, plus --group-add video.
• Wrong image tag: make sure you're pulling :latest-cuda / -openvino / -rocm, not :latest-cpu.

GPU OOM during model load

Symptom: HTTP 507 or logs with CUDA out of memory / cl_mem: CL_MEM_OBJECT_ALLOCATION_FAILURE.

• Unload any other loaded model first (POST /models/{other-id}/unload).
• Lower Max Concurrent Streams to 1.
• Switch to a smaller model family (see Hardware → VRAM budget).
• Disable TensorRT FP16 temporarily if the .plan generation itself OOMs.

Nightly task is very slow / eats CPU on a CUDA system

Symptom: LibraryUpscaleScanTask runs for hours; GPU utilization is near-zero; CPU is pinned.

• The service is running the CPU image. Check GET /status for provider.
• ffmpeg-side hardware decoding isn't enabled in Jellyfin → frame extraction is CPU-bound even if inference is GPU. Turn on Jellyfin's hardware acceleration.
• Source files are being transcoded (e.g. HEVC 10-bit to 8-bit) before extraction. Set the plugin's output codec to match source where possible.

Upscaled output exists but Jellyfin doesn't pick it up

Symptom: <file>_upscaled.mp4 is on disk but the Jellyfin library doesn't show a new version.

• File system watcher disabled: trigger a manual library scan from Jellyfin.
• Output landed outside the library root (e.g. in a cache folder). Check Plugin config Output Directory.
• Wrong owner: on TrueNAS SCALE, output must be 568:568; on Unraid, 99:100.

Comparison view is blank

Symptom: Compare tab shows "No processed videos" even though upscaled files exist.

• The comparison view only lists files named exactly <basename>_upscaled.<ext> sitting next to the source. Renamed files won't show.
• Pre-processing cache is off — enable it so previous passes are tracked.

Frame interpolation has visual artifacts

• Source has hard scene cuts: enable Scene Cut Detection in the Motion tab.
• Anime with limited animation: try rife-v4.7 (more conservative) instead of v4.9.
• Framerate doubling on a 24fps → 48fps source with judder: your display may not handle 48Hz well — target 60fps instead.

Reading logs

• Jellyfin: /config/log/jellyfin*.log, or Admin → Dashboard → Logs.
• AI service: docker logs -f ai-upscaler, or the plugin's Console tab (server-sent events).
• In-browser: DevTools → Network → filter for /Upscaler to see every plugin API call and response.

Still stuck?

Collect GET /status, GET /hardware, the last 500 lines of the Jellyfin log, the last 500 lines of the AI service log, and the plugin config (redact the API token). Open an issue at GitHub Issues with all four attached.