Why won't Kochab connect to my service?
A failed connection test at Add Service, worked through in order - protocol, port, base path, API key, network, certificate, login gate.
Adding a service in Kochab ends with a connection test, and Test & Add only saves the service if that test passes. If it does not, work through these in order - they are arranged in rough order of likelihood.
1. Protocol: HTTP or HTTPS
Kochab has a Use HTTPS switch on the same screen as the address. If the service answers on plain HTTP and the switch is on, or the service is behind a proxy that only serves HTTPS and the switch is off, the test fails before it reaches the credentials step.
Check what the service’s own web UI uses in your browser’s address bar right now. Match that.
2. Port
Kochab prefills the default port for each service type, but a container or proxy setup can move it. If you are not sure which port your service listens on, Service setup guides lists the default port and where each app displays its API key.
3. Base path
If your address carries a base path (example.com/sonarr, not just example.com), two things
have to agree: the service itself needs that same path set in its own settings, and Kochab’s
address needs to include it. Missing either one gives you a service that works in a browser and
fails everywhere else. See Reverse proxies and remote access for the exact
setting per app.
4. API key
A service’s API key copied with a leading or trailing space is a common, invisible cause - it looks identical to a correct one in a text field. Re-copy the key directly from the service (Kochab tells you where to find it for each type) rather than retyping it from memory.
5. Reachability from your phone, right now
The address you entered has to be one your phone can actually reach on its current network. A LAN address only works on the LAN. If you are testing while away from home and only a LAN address is configured, the test will fail every time, not intermittently. Kochab can hold a separate address for away from home; see Reverse proxies and remote access.
6. Certificate
A self-signed certificate that Kochab has not seen yet stops the test until you confirm it. A prompt for a certificate you HAVE seen before means the certificate changed - check why before trusting it again. See Certificate trust for what the prompt means, and Why does Kochab keep asking me to trust a new certificate? if it keeps reappearing.
7. A login gate in front of the service
A single sign-on gate (Authelia, Authentik, Cloudflare Access, Pangolin) answers with its own login page instead of passing the request through - the service is healthy and the key is correct, but nothing behind the gate ever hears from Kochab. See It works in a browser but Kochab says it’s offline for how to tell this apart from the other causes, and the fix for each gate.
8. Firewall or router
A router or host firewall can block the service’s port outright. That is rare once everything above checks out, but it happens. Try the address from a browser on the same network the phone is using - if that also fails, the block sits upstream of Kochab entirely.
If none of this finds it
Kochab never shows you the raw error from a failed connection, on purpose - a servarr or indexer error can carry the API key inside its own response, so the on-screen message stays generic. More > Settings > About & Diagnostics > Send Diagnostics gathers what actually happened, redacted, so you (or anyone helping you) can see the real cause without that risk.