Troubleshooting

Find the message you see, or the closest description, and follow the steps under it. The setup wizard and Needs attention on the Overview page use the same checks as this page.

When nothing here matches, read the log: Logs and diagnostics.

The server doesn't start

The container keeps restarting

Read why it stops:

docker compose logs --tail 100 torsher

The last lines name the reason. The common ones are below.

… is not writable by …

The container log says /data/db is not writable by 1000:1000 or the same about the downloads or library folder. The wizard shows Data folder is not writable, Downloads folder is not writable or Library folder is not writable.

Torsher writes files as the user in PUID and PGID, and that user doesn't own the folder on the host.

1. Find the owner of the folder on the host:

   ls -ln <folder-on-host>

   The third and fourth columns are the user and group IDs.

2. Set PUID and PGID in docker-compose.yml to those numbers, or give the folder to your user:

   sudo chown -R <uid>:<gid> <folder-on-host>

3. Apply the change:

   docker compose up -d

PUID and PGID must be numeric means one of them has letters or spaces in it.

SECRET_KEY is too short

If you set SECRET_KEY, it must be a random string of at least 32 characters. Generate one with openssl rand -hex 32, or remove the variable: Torsher then keeps its own key in /data/db/session.key.

Could not back up the database before updating it

A new version wants to change the database and couldn't back it up first. See Update and roll back.

The database was updated by a newer version of Torsher

You started an older version on a database a newer one already changed. Start the newer version again, or roll back with its backup.

Port 8080 is already in use

Another program uses the port. Change the left side of the port mapping in docker-compose.yml, for example '8081:8080', run docker compose up -d and open the panel on the new port.

The panel doesn't open from another device

• Check that the container is healthy in docker compose ps.
• Open http://<server-address>:8080/api/health on that device. If it doesn't load, the device doesn't reach the server: check the address (on Linux, hostname -I on the server), that both are in the same network, and the server's firewall.
• On the server itself, http://localhost:8080/panel/ should open. If it does there but not elsewhere, it's the network or the firewall.

Storage

Not enough free space

The wizard says the cache limit won't fit or free space is less than the reserve. Needs attention says free space is below the reserve or torrents are paused for lack of space. The player says The server is low on disk space.

Below the reserve, new playback doesn't start and downloads pause. In Settings → Storage:

• lower Cache limit, so Torsher removes older cache items sooner;
• or lower Keep free, if the disk really has room to spare;
• or free up space on the disk: delete downloads you don't need in Downloads.

Downloads resume on their own once there is space. Items you keep or watch right now are never removed to make room.

The file doesn't fit in the cache

The player says The file doesn't fit in the cache: the file is bigger than what is left of the cache limit. Raise Cache limit in Settings → Storage.

Kept files are copied instead of hard-linked

The wizard says Downloads and the library are on different volumes: files will be copied, and Needs attention repeats it.

A kept file is normally hard-linked from downloads into the library: it keeps seeding and takes no extra space. That only works inside one mounted volume. Two volumes, even on the same disk, turn every kept file into a copy.

Mount one folder for both and choose its subfolders in Settings → Storage, card Folders: /data/torrents and /data/library on one disk, or /storage/torrents and /storage/library with a second disk.

A library folder is unavailable

A connected folder shows Unavailable: The folder is gone or the disk is disconnected: files are hidden on the showcase but not deleted — they come back with the folder.

Check that the disk is connected and that the folder is still mounted in docker-compose.yml under the same path inside the container.

Releases are not recognized

Files in a connected folder that Torsher couldn't match to a title are under Not recognized in Library. Pick the title for them there; until then they show up under “No description” on the showcase.

A download that Torsher couldn't match waits under Needs a title on the showcase and can't go to the library yet. Pick its title there, or with Set title in Downloads. See Library.

Network and TMDB

The catalog, posters and descriptions come from TMDB. The wizard's Network step and Settings → Network check that the server reaches TMDB catalog and TMDB images.

DNS returns a wrong address

Some networks answer DNS requests for some sites with a wrong address, so the server can't reach them. Torsher notices it and says that DNS returns a wrong address.

In Settings → Network, choose DNS over HTTPS in the Default DNS card and save it. In the wizard, select Check again afterwards. If one DoH provider doesn't work, choose another. See Network.

A host is unreachable

The server can't connect to it at all. Check the server's internet connection first. If the site is unreachable from your network, add a route for its host through your proxy in Settings → Network. See Network.

No TMDB key

The wizard says No TMDB key. The image you run has no built-in TMDB key, for example a local build. The showcase says Catalog is not set up. Add your own key in Settings → Metadata. See TMDB key.

TMDB rejects the key

The wizard says TMDB rejected the key. The key was mistyped or revoked. Copy it again without spaces, or use the other of the two values on the TMDB API page. See TMDB key.

If Needs attention says the saved key can't be decrypted, TORSHER_SECRET or /data/db/secret.key changed since you saved it. Enter the key again.

The showcase says TMDB is unavailable

The showcase shows TMDB is unavailable: the server doesn't reach TMDB. Go through DNS returns a wrong address and A host is unreachable.

Sources

Prowlarr or Jackett not found

The wizard says Prowlarr and Jackett not found. It looks for Prowlarr and Jackett as compose services named prowlarr and jackett, on the Docker host, at the container network gateway and on this machine, on ports 9696 and 9117.

• The manager runs at another address or port: connect it with Connect by address. Use the address as the Torsher server sees it: localhost inside the container is the container itself.
• You have no manager yet: start Prowlarr from the install file and add the indexers you are allowed to use. See Indexers.

An indexer doesn't respond or rejects requests

Sources marks the indexer under Need attention and says why:

• The API key is rejected. An indexer from Prowlarr or Jackett uses the manager's own API key, so the key was most likely changed in the manager. Copy the current key from it and enter it in Torsher: the menu next to the manager's name → New API key. For an indexer added by hand, enter the new key with Edit.
• It doesn't respond in time. Search goes through the other indexers meanwhile. If the site is unreachable from your network, add a route through your proxy in Network.
• It is gone from the manager. It was removed in Prowlarr or Jackett, and Torsher doesn't search it. Add it back in the manager and sync, or delete it if you don't need it.

Search finds nothing

• Check that Sources has at least one working indexer.
• The Sources screen on the TV says how many indexers didn't answer.
• Your indexers may simply have nothing for this title. Torsher searches only the sources you connected.

Playback

Playback waits for peers

The player shows Waiting for peers: Nobody is sharing this file yet. The torrent may be rare: wait or pick another one. In the panel, the download says Nobody is seeding this torrent right now. Torsher continues as soon as it finds peers.

Choose another release with more seeders on the Sources screen. If every release waits, check that the server reaches the internet.

The torrent isn't ready or has no file list

The torrent isn't ready yet: the server is still getting the file list from peers. Try again in a minute. If the panel says Peers didn't send the file list. Check the magnet link and try again, or add the .torrent file., choose another release.

The video doesn't play

The player says The player can't open this format: the device can't decode this video and the server couldn't transcode it. Open Settings → Playback: it shows what the server can transcode with. See Hardware transcoding. If the page says Nothing to transcode with, the server can't transcode at all: pick another release in a format the device plays.

A GPU was found but failed the test

The server transcodes on the CPU instead. See Hardware transcoding.

The torrent engine isn't running

The player says The torrent engine isn't running, or Needs attention says the engine crashed. Restart the container:

docker compose restart torsher

If it keeps crashing, look for Engine entries in Logs and report it.

TVs and devices

The TV doesn't show a code

The TV shows Couldn’t get a code: it doesn't reach the server. Check that the server is running and that the TV is in the same network, then open http://<server-address>:8080/api/health in the TV's browser. If it doesn't load, the TV can't reach the server at that address.

The code is not accepted

The code changes on its own after a while. Enter the one the TV shows right now. See Connect a device.

A device says it is not connected

The showcase shows Not connected. The device was removed in Profiles & devices, or the browser on it lost its site data. Connect it again with a new code.

Backups

The backup folder is unavailable

The disk or NAS share isn't mounted into the container, or isn't writable by PUID and PGID. Scheduled backups are skipped until it is back. See Backup and move.

No backup for more than two days

Scheduled backups are failing or off. Settings → Backups shows the last error. Fix it, then select Back up now to check.

Still stuck

Collect the version, the log and the steps, and report the problem.