Troubleshooting¶

This page is for the owner, and anyone helping: how to find out what is wrong, in which order to look, and an index of every problem already solved once, grouped by area. The fixes themselves live in known-issues.md, which ships with the stack-logs skill so an AI agent reads the same list.

How to diagnose¶

flowchart TD
    start["Something is wrong"] --> hc["stack-health: what is failing?"]
    hc --> kuma["Uptime Kuma: since when?"]
    kuma --> logs["Dozzle or the stack-logs skill: why?"]
    logs --> known{"In the known issues?"}
    known -->|yes| fix["Apply its fix, then stack-health again"]
    known -->|no| deeper["vpn-check, drive-health, or the app's own logs"]
    deeper --> fix

Run stack-health first (health in the terminal). It checks storage, systemd units, security, backups, every service, monitoring, Cleanuparr, the indexers and the VPN, and prints OK or FAIL per line with a summary N passed, M failed. A yellow UPDATES line is information, not a failure. It exits non-zero when anything failed. It isn't strictly read-only: it writes a hardlink test file on the media drive and starts short-lived curl containers. arr-health.timer runs it every 6 hours with --notify and pushes failures to your phone.
Uptime Kuma tells you when. The status page, http://<tailscale-ip>:3003/status/stack, has every service's recent checks, so you can see whether something is down now, went down at a certain time, or has been flaky (Dashboards).
The logs tell you why. Dozzle, http://<tailscale-ip>:8888, streams every container's log with search (Dashboards). In a terminal:
```
docker compose ps --format '{{.Name}} {{.Status}}'
docker logs --since 30m <service> 2>&1 | grep -iE 'error|warn|fatal|exception' | tail -30
```
Every container is named after its compose service. Or ask an AI agent with the stack-logs skill: it reads the logs and matches them against the known issues (AI agent). 4. For the VPN, run vpn-leak-test (leaktest) or the vpn-check skill, which also proves qBittorrent and slskd sit inside gluetun's network and that traffic can't bypass the tunnel (VPN and ports). 5. For the media drive, the drive-health skill reads its SMART data, temperature and USB link, and Scrutiny shows the history (Maintenance).

Diagnosis is safe. Fixing often isn't: restarting services, touching the VPN, editing .env or restoring data interrupts people, so check that nothing is playing in Jellyfin first. The things never to do are listed at the end of the known issues.

Where a failing check points¶

`stack-health` section	Look at
STORAGE	Storage and boot, disk space, drive health
SYSTEMD	systemd reference, Host setup
SECURITY	Security, Host setup
BACKUPS	Backups
SERVICES, MONITORING	The app's logs; Monitoring
CLEANUP & INTROS	Cleanuparr
INDEXERS	Indexers
VPN	VPN and ports

Known issues by area¶

Each link opens the entry with its symptom, cause and fix.

VPN and torrents¶

Searching and downloading¶

Watching and subtitles¶

Quick answers for viewers (buffering, nothing new showing, works only at home) are in Watching.

Music¶

Games¶

Access¶

Monitoring and dashboards¶

Storage and configuration¶

Solved a new problem? Add it to known-issues.md in the same shape (symptom, cause, fix) and link it from the matching group here.