# 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.

Canonical: https://kochab.io/docs/troubleshooting/service-wont-connect/

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](/docs/service-setup/) 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](/docs/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](/docs/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](/docs/cert-trust/) for what the prompt means, and
[Why does Kochab keep asking me to trust a new certificate?](/docs/troubleshooting/certificate-keeps-asking-to-trust/)
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](/docs/troubleshooting/works-in-browser-not-kochab/)
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.