Common Setup Failures

Start here for path, mount, networking, Torznab URL, permission, recovery, and cleanup-scope problems.

Docker paths and mounts

cross-seed and your torrent client must see the same data at the same path. There is no path remapping layer in cross-seed.

If qBittorrent says a torrent is saved at /data/torrents/movies/Movie, then the cross-seed container must also be able to access that same file at /data/torrents/movies/Movie. If Deluge says the save path is /downloads/tv/Show, then cross-seed must also see /downloads/tv/Show.

Working Docker Compose pattern

Mount the same host path at the same container path in qBittorrent, the Arrs, and cross-seed:

services:
    qbittorrent:
        image: lscr.io/linuxserver/qbittorrent
        volumes:
            - /mnt/user/data:/data

    radarr:
        image: lscr.io/linuxserver/radarr
        volumes:
            - /mnt/user/data:/data

    sonarr:
        image: lscr.io/linuxserver/sonarr
        volumes:
            - /mnt/user/data:/data

    cross-seed:
        image: ghcr.io/cross-seed/cross-seed:6
        container_name: cross-seed
        user: 1000:1000
        ports:
            - "2468:2468"
        volumes:
            - /mnt/user/appdata/cross-seed:/config
            - /mnt/user/data:/data
        command: daemon

Then use paths under /data everywhere:

module.exports = {
	torrentClients: ["qbittorrent:http://user:pass@qbittorrent:8080"],
	dataDirs: ["/data/media/movies", "/data/media/tv"],
	linkDirs: ["/data/torrents/cross-seed"],
};

Broken Docker Compose pattern

This exposes the same host tree at different container paths:

qbittorrent:
    volumes:
        - /mnt/user/data/torrents:/downloads

cross-seed:
    volumes:
        - /mnt/user/data:/data

If qBittorrent reports /downloads/Movie, cross-seed will look for /downloads/Movie. It will not translate that to /data/torrents/Movie.

Hardlinks across Docker mounts

Hardlinks and reflinks must be created within the same filesystem mount. In Docker, separate volume declarations are separate mount points from the container's point of view, even when they are on the same host disk.

This will often fail for hardlinks:

volumes:
    - /mnt/user/data/torrents:/torrents
    - /mnt/user/data/cross-seed:/cross-seeds

Prefer one shared parent:

volumes:
    - /mnt/user/data:/data

Then set linkDirs to a path under that same mount:

linkDirs: ["/data/cross-seed"],

Diagnosing path and linking errors

Use these checks from inside the cross-seed container:

docker exec -it cross-seed sh
ls -la /data/torrents
ls -la /data/torrents/path/from/client
touch /data/torrents/.cross-seed-write-test
rm /data/torrents/.cross-seed-write-test

If ls cannot find the path that your torrent client reports, fix the mounts or save paths first.

Symptom	Check first
`Linking failed ... not found`	`cross-seed` cannot see the source file at the client-reported path, or the source torrent is missing files.
`invalid data`	The path points at the wrong file/folder, or the file is not the expected torrent data.
Injected torrent stays at `0%`	The torrent client cannot see the linked data at the injected save path.
`EXDEV` or hardlink failure	Source and destination are on different filesystems or different Docker mounts.

Torznab and Prowlarr URLs

The torznab option needs each indexer's Torznab endpoint, not the base Prowlarr API URL.

In Prowlarr, open the indexer and copy the Torznab/RSS URL for that indexer. The URL should include the indexer ID before /api.

Correct:

http://prowlarr:9696/1/api?apikey=YOUR_KEY
http://prowlarr:9696/2/api?apikey=YOUR_KEY

Wrong:

http://prowlarr:9696/api?apikey=YOUR_KEY
http://prowlarr:9696/api/v1/indexer?apikey=YOUR_KEY

responded with invalid XML usually means the URL returned JSON or HTML instead of Torznab XML. Check for a Prowlarr JSON API URL, login page, reverse proxy error page, or wrong indexer path.

From inside Docker, 127.0.0.1 and localhost mean "this container", not "another container". Use the service name, such as http://prowlarr:9696, when both containers share a Docker network.

Docker networking and webhooks

Test the exact network path with /api/ping before configuring qBittorrent, Deluge, autobrr, or an Arr import script.

From another container on the same Docker network:

curl http://cross-seed:2468/api/ping

From the host, if port 2468 is published:

curl http://localhost:2468/api/ping

From another machine on your LAN:

curl http://192.168.1.10:2468/api/ping

Choose the base URL from the caller's network context:

Caller	Usually use
qBittorrent in the same Compose network	`http://cross-seed:2468`
qBittorrent sharing the same Gluetun/VPN network namespace	`http://localhost:2468` if `cross-seed` is in that namespace too
qBittorrent on the Docker host	`http://localhost:2468`
qBittorrent on another LAN host	`http://HOST_LAN_IP:2468`
qBittorrent in a different Docker network	Put both containers on a shared network or use the host LAN IP

Common curl errors:

Could not resolve host: the hostname is not visible from where curl runs. Use the Compose service name on a shared Docker network, or an IP address.
Connection refused: the host resolved, but nothing is listening there or the port is not published/reachable.
401 Unauthorized: /api/ping works, but protected endpoints need the API key. Run cross-seed api-key and include ?apikey=... or X-Api-Key.

Do not expose the cross-seed API to the public Internet.

Config and permissions

Let cross-seed generate config.js first, then edit the generated file.

If edits do not stick:

Confirm you are editing the active config directory.
Check that the container user can read and write /config.
On Docker, set user: to the same UID and GID as your torrent client.
On Unraid, check appdata permissions and the template's host paths.
On Synology or Unraid, avoid editors that save through a temporary file with different ownership.
Restart cross-seed after editing config.js.

If config.js is invalid JavaScript, startup will fail. Fix the syntax error instead of deleting the config or database.

Before asking for help

Include these when asking for help:

cross-seed version.
Install method: Docker, Unraid, npm, seedbox package, or other.
Torrent client and version.
Redacted config.js.
Startup logs.
<config dir>/logs/verbose.current.log.
Exact command or webhook URL used.
Docker Compose, Unraid template, or seedbox topology if applicable.
The save path shown by the torrent client for one affected torrent.

Redact API keys, passkeys, usernames, passwords, and tracker domains.

Docker paths and mounts​

Working Docker Compose pattern​

Broken Docker Compose pattern​

Hardlinks across Docker mounts​

Diagnosing path and linking errors​

Torznab and Prowlarr URLs​

Docker networking and webhooks​

Config and permissions​

Before asking for help​