Troubleshooting

Troubleshooting

Every entry here is a failure that actually happened on a real host, with what it meant and how it was fixed.

The controller

It will not start: "mounts denied" / "path is not shared from the host"

Error response from daemon: mounts denied:
The path /share/Container/docker is not shared from the host

deploy/.env names a host root that does not exist on this machine. Common after copying an .env between hosts.

Check .env against reality:

grep '^HOST_' .env | cut -d= -f2 | while read p; do
  [ -e "$p" ] && echo "ok      $p" || echo "MISSING $p"
done

Correct the paths and recreate the controller. Once it is running, change roots in the app instead — Keelarr rewrites .env for you.

It starts, then is killed and restarted forever

The healthcheck allows twenty seconds and three retries. Initialisation inspects every container and attaches the controller to each service network, which took four minutes on a busy NAS — so a perfectly healthy controller was marked unhealthy and restarted mid-startup, forever.

Fixed by listening before initialising: the port opens in seconds, /api/health answers immediately, and the slow work continues behind it. If you see this, you are on an old build — update.

Everything returns 401

Expected without a session. Sign in. If you have lost the password, delete auth.json from the data directory and restart; the first-run setup runs again. This does not touch anything else.

Deploying a service

"Host port 8080 is already in use"

Could not deploy SABnzbd. Host port 8080 is already in use by another
container or service. Change this app's port in Settings, or stop
whatever holds 8080.

Exactly what it says. Find the holder:

docker ps --format '{{.Names}}\t{{.Ports}}' | grep 8080
lsof -nP -iTCP:8080 -sTCP:LISTEN

Then either stop it, or change the app's port in Settings and redeploy. A service moved to a new port is re-resolved by the wiring automatically.

A container is running but nothing can reach it

Check whether it actually attached to a network:

docker inspect -f 'nets={{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}' <name>

An empty result with a NetworkMode set means the container came up but never joined the network — usually the aftermath of a failed create, such as the port clash above. Redeploy it.

Wiring

SABnzbd answers 403 to everything

A fresh SABnzbd whitelists only the hostname it sees itself as — inside a container, the container ID — and refuses its own container name, which is what everything else uses.

http://sabnzbd:8080/api?mode=version    → 403 Forbidden
http://172.25.0.9:8080/api?mode=version → {"version":"5.1.0"}

Keelarr fixes this itself now, by appending the hostname through SABnzbd's own API addressed by IP. If you are doing it by hand, add the container name to Config → General → Host whitelist, keeping the entries already there.

"Nothing could be written: 2 cannot be reached"

Not a failure — the honest version of "nothing to do". Some links are blocked, still starting, or deliberately left alone. Run Check Wiring for the detail: each link says which state it is in and why.

Note this is different from "every connection is already configured", which Keelarr only says when every link was confirmed correct.

A connection is reported as blocked

The two containers genuinely cannot reach each other — different networks, nothing published. The reason names both sides. Put them on a shared network, or publish a port.

Keelarr reports this rather than writing an address that would time out later.

Drift: "already pointing elsewhere and left alone"

An existing connection points somewhere unexpected. Keelarr never overwrites these, because it is usually deliberate. Fix it in the app if it is not.

Radarr needs a "movies" category

An Arr refuses a download client with no category. Keelarr creates the category first — if that fails, the download client is unconfigured and the reason is reported. Usually the download client refused the category call, which on a fresh SABnzbd is the 403 above.

Prerequisites

"Prowlarr has no indexers"

Correct, and only you can fix it. Nothing in the stack can find releases until at least one indexer exists. Keelarr never touches indexers — they carry credentials you paid for.

qBittorrent wants a password you never set

It generates a temporary one on first start and prints it in its logs:

docker logs qbittorrent 2>&1 | grep -i password

Set a permanent one in its web UI. On a LAN you may also want Bypass authentication for clients on localhost / whitelisted subnets.

Upgrades

A pull is killed part way

Pulls are judged on progress, not a deadline — two minutes of silence means stalled. If yours is genuinely slow but progressing, it will not be killed. A 175-second pull completing normally is the case this was built for.

Rollback says it is unavailable

There is nothing to roll back to: the "new" image had the same digest as the one already running, so nothing changed. Reported rather than pinning the service to itself.

Getting help

Include: your host and Docker version, what you did, what was reported, and the relevant part of data/keelarr.log.

Redact before pasting: API keys and anything with ?apikey=, indexer names, Usenet hostnames, Plex tokens, and any public address.

Open an issue. If you are on a platform nobody has tried, a report that it worked is as useful as a bug.