Skip to content

Troubleshooting

Start at System → Status: the health checks name most problems directly, and System → Events and a job's own log have the details.

Nothing is transcoded after a grab

  • The job sits at Waiting for import: Radarr / Sonarr have not imported the download yet. Check the *arr app's queue — an import that is stuck there (a .iso, a sample, a failed unpack) never reaches Rexarr. Full discs are expected to stay import pending — that is how full-disc releases work.
  • The file was imported but Rexarr cannot see it: System → Status says so. Add a path mapping.

"X is not visible to Rexarr" / wrong paths

Radarr in Docker says /data/media/movies/…; Rexarr on the host sees /Volumes/Media/Movies/…. Add a path mapping per app (remote → local). Mappings work in both directions, so they also fix delivering rips back to the app. For the rip folder, use Settings → Disc ripping → Check import access.

An encoder is missing

System → Status → FFmpeg lists what your ffmpeg actually has. Install a build with the encoder you want (or point Settings → Encoding → FFmpeg at one) — for example a CUDA-enabled ffmpeg for NVENC, or jellyfin-ffmpeg for RKMPP. Profiles naming a missing encoder are flagged in the profile editor.

"Unknown system error -86" on macOS

An Intel-only binary (ffmpeg, fre:ac or MakeMKV) on an Apple silicon Mac without Rosetta. Install the arm64 build, or install Rosetta. Status and the health checks spell this out, including binaries that are not executable or not where the setting points.

Hardware encoding fails or is slow

  • Use Test in Settings → Encoding → Transcoding: it encodes 3 seconds and shows the fps or the exact ffmpeg error.
  • A failed hardware encode is retried on the CPU automatically; the job log and Events say so.
  • In Docker, pass /dev/dri for QSV / VAAPI, and remember NVENC needs the NVIDIA container runtime.
  • Hardware encoders need more bitrate for the same quality — for archiving remuxes, software x265 / SVT-AV1 is the better choice.

An encode never finishes

Set Stop stalled encodes after (Settings → Encoding → FFmpeg) so a stalled network share or a hung driver fails the job instead of blocking the queue. The queue limit is enforced from job creation, so a probing job cannot let extra encodes start.

Discs

See the disc troubleshooting table for the full list. The common ones:

  • Nothing imported, rip failed with cannot see … — the rip directory is not reachable by the app at that path. Fix the mapping and run Import rip folder now; the files are still there.
  • No titles found on this disc — the OS mounted it, or MakeMKV cannot decrypt it (Blu-ray needs a key).
  • MakeMKV could not open the disc — the message says which: a drive not ready yet (Rexarr waits and tries once more by itself), a drive MakeMKV did not find, an unreadable disc image, or a mounted volume on macOS.
  • Drives vanish, or a disc is in the tray and Rexarr lists no drives — usually the drive has dropped off the USB bus, not a fault in Rexarr. drutil list on macOS shows whether the machine can see it at all. Two USB optical drives need more power than a bus-powered hub provides: plug each one directly in, or use a powered hub. See Drives that come and go.
  • A title is missing — it is shorter than Minimum title length; lower it or tick Include extras and specials.
  • Cannot create the rip folder … — the folder in Settings → Disc ripping → Rip folder cannot be made. The message names the deepest folder that does exist and whether Rexarr can write to it. On macOS, a rip folder under /Volumes that is not mounted reports as a permission problem, because only root may create folders directly in /Volumes — mount the drive or share first, and check the volume name matches.
  • The machine went to sleep mid-rip — keep Keep this computer awake while ripping or encoding on (Settings → Encoding); System → Status → Sleep shows whether the inhibitor is held.

Music

  • fre:ac missing — install it and set the path in Settings → Connections → fre:ac. The Docker image has fre:ac but no WavPack or Monkey's Audio encoder.
  • A CD is identified as the wrong album — if the release is labelled similar length only, unconfirmed, it was never recognised: MusicBrainz offered it because its track lengths are close. Pick another from the list, search by artist and album, or leave it on Generic track names. Rexarr will not apply such a suggestion by itself, and auto-rip will not start on one.
  • An album will not import into Lidarr — a single image + cue album is split automatically; if it already left Lidarr's queue, use Music → Import Folder.

"Could not reach Rexarr" or a route that is not there

Two different failures, and the message says which:

  • Could not reach Rexarr — the request got no answer at all. Rexarr is restarting, stopped, or on a different address than the page was opened from (a changed port, a reverse proxy, a container that was recreated).
  • This Rexarr server has no PUT /api/… — the page is from a newer build than the server answering it. Rexarr serves the web files by reading them per request, so rebuilding the client goes live immediately while the server keeps running the code it started with. Restart Rexarr after a rebuild, then reload the page.

Locked out of the UI

Start Rexarr once with REXARR_RESET_AUTH=1 to turn authentication off, then set it up again under Settings → General → Security.

Port already in use

REXARR_PORT (or PORT) wins over the setting and locks the field in the UI — check it is not set in your service file, shell profile or Docker environment. Host changes made in the UI rebind the server in place and fall back to the old port if the new one cannot be bound.

Reporting a bug

System → Status → Report an issue opens a GitHub issue with your version, platform and install method filled in. Please include the job log or disc log, and say what you expected. If you are not sure it is a bug, ask in Discussions → Q&A instead — half of what lands there is a path mapping. Security problems go to SECURITY.md instead.