Doctor

The Doctor checks the parts Freetvarr depends on and says what to fix. Open it from SETTINGS → HELP → RUN DOCTOR, from the TVHEADEND cell on the dashboard when TVHeadend does not answer, or by adding #/doctor to Freetvarr's address in the browser's address bar.

The Doctor only reads. It sends GET requests to TVHeadend and Plex, and it looks at folders without writing to them. It never saves settings, changes TVHeadend, refreshes Plex, or starts a test encode.

Each check gets one of these results:

• PASS: nothing to do.
• WARN: Freetvarr works, but something costs you space, guide data, or picture quality.
• FAIL: something Freetvarr needs is broken. The row says how to fix it and links to the matching docs.
• SKIP: the check cannot run yet, usually because an earlier check failed. Fix that one first.

Failing rows come first. Press RE-RUN to check again. A check that gets no answer in 8 seconds fails.

From a source checkout, npm run doctor outputs the same checks in the terminal. It reads the settings from Freetvarr's database, so run it on the computer that runs Freetvarr.

Connection

Asks TVHeadend for its version (/api/serverinfo). It fails when no TVHeadend address is set, or when nothing answers at that address. It warns when TVHeadend is older than a 4.3 build. See Wizard connection test.

Login

Checks that TVHeadend accepts the username and password. A 401 means TVHeadend asked for a login and did not get a valid one. A 403 means a wrong password, an address outside Allowed networks, or an access entry with no rights. See TVHeadend 401 or 403.

User rights

Reads the tuner status, which needs Admin, and the upcoming recordings, which need Video recorder. A 403 on either names the right to tick on the TVHeadend access entry. The rights table lists every right Freetvarr uses. The Doctor cannot test the Streaming rights without starting a stream, so it does not check them.

Open access

Reads TVHeadend's access entries. It warns when an enabled entry with username * has Admin (then anyone on that network can change TVHeadend without a login). A fresh linuxserver TVHeadend starts with such an entry. See Secure TVHeadend.

Tuners

Counts the tuners in TVHeadend's hardware list and the inputs in its status page. It fails when there are none, and warns when no tuner is turned on. It also warns when a tuner has a link-local 169.254.x.x address, because that address can change if you move the tuner. See Missing tuner.

Channels

Counts TVHeadend's channels. It fails at 0 (the CHANNELS step of the setup wizard adds them). See No channels.

Guide depth

Skips with "No channels yet" when TVHeadend has none. Otherwise it finds the last programme in TVHeadend's TV guide and counts the channels with nothing in the next 24 hours. It fails when the TV guide ends within 12 hours. It warns when the TV guide ends within 48 hours, or when more than a quarter of the channels are empty. See Empty guide.

Channel logos

Counts the channels that have a TVHeadend icon. It skips when there are no channels. It warns when Prefer picons over channel icons is on but no Picon path is set, because TVHeadend then reports no icon at all. See Missing channel logos.

Recordings folder

Checks that the recordings folder exists inside the Freetvarr Docker container and is readable. See TEST PATH failures.

TVHeadend recording path

Compares Recording system path on TVHeadend's default DVR profile with the TVHeadend recordings path in SETTINGS. They must match. See CHECK TVHEADEND mismatch.

Media folder

Checks that the media folder exists and that Freetvarr can write to it. When it cannot, the row names the folder's owner and the user Freetvarr runs as. See Permission errors.

Hardlinks

Makes a real test hardlink from the recordings folder into the media folder and into the one-off folder. If a link fails, each import copies the file, and every episode uses twice the space until TVHeadend's copy is deleted. The warning says either that the folders are on different disks, or that they are on one disk but in separate mounts. For separate mounts, mount one folder that holds both. See One shared mount.

Free space

Reads the free space on the recordings and media folders. It warns under 20GB or 10% free, and fails under 2GB. Sizes of 1000GB or more show as TB. Recordings fail when the disk fills. With Docker on a Mac or Windows PC, the figure is Docker's virtual disk. The real limit is your computer's own disk.

Plex library

Lists Plex's library sections. It skips when Plex is not set up. It fails when Plex rejects the token or does not answer, or when the chosen section is missing or is not a TV library. It warns when no folder of that section ends in the same two folder names as the media folder. See Plex not refreshing and the library folder.

Syncs

Reads the last finished sync and the sync schedule. It warns when the last sync failed or had failed imports. It fails when a schedule is set but not running. It works without Plex, so it has its own SYNCS group on the Doctor page. See Syncs.

Live TV encoder

Reports the video encoder Freetvarr chose for live TV when it started. It fails when ffmpeg is not installed. It warns when live TV falls back to software encoding, because HD channels then load the processor. Setting LIVE_TV_TRANSCODE=software yourself passes, and so does Docker on a Mac or Windows PC, which cannot use the graphics chip. See Hardware transcoding.

Ad removal tools

Runs only when ad removal is on. It checks that comskip, ffmpeg, and ffprobe are on the PATH, without starting them. The Docker image includes all three. See Ad removal.

Time zone and network

Warns when no time zone is chosen and the system runs on UTC, or when TZ or the stored zone is not a known zone, because the TV guide and recordings then show the wrong times. Choose your zone in SETTINGS → SCHEDULE, or correct TZ in your .env (for example Australia/Sydney). It also warns when Freetvarr has only Docker bridge addresses, which means it is not on host networking. See Wrong timestamps and Container name lookups.