Troubleshooting

🇬🇧 English · 🇫🇷 Français

Troubleshooting

The gotchas people actually hit.

Credentials regenerate on every restart

Cause: the config volume isn't mounted at /config (singular). The image reads/writes config, resume data and the durable store under /config; if you mount your host folder elsewhere, each boot starts from an empty config and regenerates the admin password and API key. Fix: mount your host folder at /config exactly. Grab the admin password from docker logs after the first (correct) boot.

qBit import / a LAN qBittorrent can't be reached (behind a VPN)

Cause: when Hydra runs inside a VPN container (gluetun), its egress goes out the tunnel, so it can't reach a qBittorrent on your LAN (e.g. the import wizard). Fix: allow the LAN subnet out of gluetun — on the gluetun service set FIREWALL_OUTBOUND_SUBNETS=192.168.x.0/24 (exact name, plural, with /24), then up -d. Also remember localhost is the VPN netns, not your host — use the LAN IP.

Recheck / verify returns an error on a race torrent

By design. Verify/recheck is hoard-only — the race engine has no piece picker to record per-piece verification. Recheck the torrents you intend to seed. See Adding Torrents and Existing Data.

Recheck reports 0/N on data I'm sure exists

Almost always a save-path mismatch — the file is one directory level off from where the engine looks. Single-file torrents read save_path/<name>; multi-file read save_path/<name>/<files…>. Line up the save path with the actual location.

qBit recheck with hashes=all does nothing

Intentional. A mass recheck over a 100k-torrent hoard would be a disk storm, so all is ignored. Pass explicit info-hashes.

Can't seed on both engines behind one VPN port

One forwarded port serves one engine (two engines = two processes, can't share an inbound TCP port). Run one engine per gluetun with a front-only controller — see Deployment Topologies.

The UI is briefly unreachable right after a restart

The API comes up after the engines load. On a large hoard that reload takes a bit (resume + durable-store import), so give it a minute after a restart before the web UI answers. This is normal and doesn't re-hash your data.

First web login fails / "auth not configured"

The [auth] block has no password_hash yet. On a fresh install Hydra generates one and prints the plaintext once in the logs; grab it there. To set your own: docker run --rm --entrypoint hydra <image> hash-password '<pw>' and paste the hash into [auth] password_hash.