General Troubleshooting

General Troubleshooting

Each entry follows the same shape: a clear Symptom, the most likely Cause, and the exact Fix. Start at “Where to look first” if you do not yet know which entry applies.

Where to look first

Before diving into a specific entry, check these three sources — they answer most questions on their own:

1. Health endpoint — confirms whether the backend itself is up and which subsystems are reporting errors.

   curl http://<HOST_IP>:5765/api/v1/health/detailed

2. Container logs — show the live error and stack trace, not the user-friendly UI message.

   docker logs sublarr --tail 200 --follow

3. Sublarr UI — open Activity for per-item error details, Queue for stuck jobs, and Settings → Providers for circuit-breaker state.

To enable verbose logs while debugging, set SUBLARR_LOG_LEVEL=DEBUG and restart the container.

---

Sublarr does not start

Symptom: The container exits within seconds of docker compose up. docker logs sublarr shows database is locked or OperationalError.

Cause: Two Sublarr containers were pointed at the same SQLite file in /config, or the /config mount is on a filesystem that does not support file locking (some network shares).

Fix: Run only one container per <CONFIG_PATH>. To run multiple replicas, switch to PostgreSQL — see PostgreSQL Setup. For network-mounted /config, move the volume to a local-disk path or to PostgreSQL.

---

Subtitles are never downloaded

Symptom: Items appear in Wanted but no candidate is ever picked, or the row stays at 0/0 provider attempts.

Cause: One of:

• No provider is enabled, or every enabled provider has invalid credentials.
• The series has no Language Profile assigned in Library.
• The provider’s circuit breaker is open after repeated failures.
• The path mapping between Sonarr/Radarr and Sublarr does not resolve, so candidates cannot be matched to a real file on disk.
• Candidates exist but no candidate clears the Minimum Score threshold of the active Language Profile — the search succeeds, the download is held back.

Fix:

1. Open Settings → Providers, confirm at least one provider is Enabled and shows a green health dot. Click Test to validate credentials.
2. In Library, open the series and confirm a Language Profile is assigned.
3. If a provider’s status is Open, wait for the cooldown or click Reset Circuit Breaker in the provider’s detail pane.
4. In Settings → Integrations → Path Mapping, verify your Sonarr/Radarr paths translate to the paths Sublarr sees in /media/....
5. Open Activity for the real per-item error messages. If you see candidates with scores below the threshold, lower the Minimum Score in the Language Profile or adjust the Score Modifier of the contributing provider.

---

A specific provider keeps failing

Symptom: One provider consistently shows red status, or Activity lines from that provider always end in circuit_open or auth_error.

Cause: Expired API key, wrong endpoint, or the upstream service is rate-limiting your IP.

Fix:

1. Open Settings → Providers and click the provider.
2. Re-enter the API Key (or Username / Password) and click Test.
3. If credentials are correct but you see 429 errors, raise Rate Limit Throttle (minutes) under provider settings, or add a second key via API Key Pool to spread load.
4. If the upstream is down, disable the provider until it recovers — Sublarr will continue searching the rest.

---

Translation jobs are stuck or not running

Symptom: Translation entries pile up in Activity → Translations with status queued or in_progress for minutes.

Cause: Ollama is unreachable, the configured model is not pulled, or the LLM host is overloaded.

Fix:

1. Confirm Ollama is reachable from the Sublarr host:

   curl http://<OLLAMA_HOST>:11434/api/tags

   You should see a JSON list of pulled models.

2. Confirm the model configured in Settings → Translation → Ollama Model is in that list. If not, pull it on the Ollama host:

   ollama pull qwen2.5:14b

3. Check Activity → Translations for the per-job error message.

4. Look at container logs for repeated connection refused or model not found lines:

   docker logs sublarr --tail 100 | grep -i ollama

5. If the LLM host is GPU-bound, reduce Translation → Performance → Concurrent Workers in Settings → Translation.

---

Subtitles do not appear in Plex / Jellyfin / Emby after download

Symptom: Activity shows the download succeeded and the file is on disk, but the media server does not pick it up.

Cause: Either the media server has not been triggered to rescan, the API key is wrong, or the media server sees a different file path than Sublarr.

Fix:

1. Open Settings → Integrations → Media Servers, confirm your media server is configured, and click Test.
2. If Test fails, fix the URL or API key first.
3. If Test succeeds but the file still does not appear, trigger a manual library scan in the media server’s own UI.
4. Verify both Sublarr and the media server see the same file path. They must agree on the file’s location — if Sublarr sees /media/Anime/Foo.mkv and Plex sees /data/Anime/Foo.mkv, configure path mapping in Settings → Integrations.

---

Wanted scanner runs but finds nothing new

Symptom: The scheduled scan runs (visible in Activity → Recent) but the Wanted count stays at the same number for hours or days.

Cause: The scanner is correctly determining that every file already has matching subtitles. This is normal once your library is fully covered. If you expected new items, the most likely cause is a stale Sonarr/Radarr connection.

Fix:

1. Run a manual scan from Wanted → Scan now to confirm.
2. If you expected new items, open Settings → Integrations and click Test on each Sonarr/Radarr instance.
3. Verify recent episodes are visible in Library — if they are missing, the integration is failing silently.

---

High CPU during scans

Symptom: During a scan, host CPU is pinned at 80–100%.

Cause: The scanner runs ffprobe on every video file to detect existing embedded tracks. On large libraries this is CPU-bound by design.

Fix:

1. Lower Settings → System → Scanner Workers (default 4 — try 2).
2. Increase the scan interval in Settings → System → Scheduler (every 12 hours is usually fine for stable libraries).
3. Enable incremental scanning so only changed files are re-probed.

---

Health endpoint returns errors

Symptom: curl http://<HOST_IP>:5765/api/v1/health/detailed shows one or more subsystems as error or degraded.

Cause: Each error message names the failing subsystem (providers, translation, media_servers, scheduler, database). The detailed response includes a one-line reason per subsystem.

Fix: Match the subsystem name to the section above:

Subsystem	Section
providers	”Subtitles are never downloaded” / “A specific provider keeps failing”
translation	”Translation jobs are stuck or not running”
media_servers	”Subtitles do not appear in Plex / Jellyfin / Emby after download”
scheduler	”Wanted scanner runs but finds nothing new”
database	”Sublarr does not start”

---

Still stuck

If none of the entries above match, gather these three pieces and open a GitHub issue:

1. The exact error message from Activity or container logs.
2. The output of curl http://<HOST_IP>:5765/api/v1/health/detailed.
3. Steps to reproduce — including which media file, which provider, and which language profile.

For setup help and live discussion, see the Discord.