Troubleshooting

Most problems with a service in Pocket Homelab come down to one of a handful of causes. This page walks through them in the order to check.

Reading a “Test connection” failure

Every service form has a Test connection button (disabled when the URL is empty, the service is paused by the free limit, or it has no test at all). It saves your draft first, then makes one real request and reports back in plain language:

Message	What it means	What to check
timed out	The request never got a response in time.	Is the host up? Is your VPN/Tailscale connected?
connection refused	Something answered, but not the service.	Wrong port, or the service isn’t listening there.
host not found	DNS could not resolve the hostname.	Try the IP address instead; check your DNS/split-tunnel setup.
TLS failed	The certificate isn’t valid for that hostname.	Use a certificate the device trusts (see below) or switch to plain HTTP over your VPN.
offline	The device itself has no network connection.	Check Wi-Fi/cellular; this isn’t about the server at all.
… → HTTP 401 / 403	The server answered, but rejected the request.	Recheck the account, token or password, and what permissions it has.

These come straight from the app’s own error text (describeError in the shared networking layer), the same wording appears in the Home tile’s inline error and in the service screen if the connection drops mid-use.

Under a failed test, and in the guided Connect form, the app also explains the failure in words with the likely fixes first (““nas.example.com” did not answer.”, “Jellyfin was not found at this address (HTTP 404).”, “Something answered, but it does not look like Paperless.”) and keeps the raw error underneath. The full list is in Connect your services.

Self-signed certificates and plain HTTP

Pocket Homelab does not add exceptions for self-signed or otherwise untrusted certificates, a TLS failed error means exactly that, whatever the reason. You have two practical options:

• Put a certificate the device already trusts in front of the service: a reverse proxy with a Let’s Encrypt certificate, Tailscale HTTPS for a *.ts.net name, or your own internal CA properly installed on the device, or
• Use a plain http:// URL instead, but only for an address on your local network. Never expose a service in plain HTTP to the open internet just to work around this.

Reaching a service over Tailscale or another VPN

Pocket Homelab does not configure or manage any VPN for you, it just makes an HTTP request to whatever URL you give it. If a service works in a regular browser on the same device but fails in the app:

• Confirm the VPN is actually connected on the device you’re testing from, not just the server.
• Try the service’s Tailscale/VPN IP address directly instead of a hostname, to rule out DNS (over https://, since iOS blocks plain http to a Tailscale address).
• Some VPN configurations only route certain subnets or exclude local traffic. Check the client’s split-tunnel or exit-node settings if a timed out or host not found error persists with the VPN connected.

Timeouts and inline errors

Most requests use an 8 second timeout; TrueNAS, Scrutiny and Speedtest Tracker use 10 seconds, ntfy’s history poll uses 15 seconds, and Backrest, which can have a lot of history to read, uses 15 seconds too. A slow but reachable service can still time out under this budget even though a browser would eventually load it.

When a request fails, the app does not blank the screen: it keeps the last value it successfully loaded and shows a short red inline error underneath (an exclamation-triangle icon, up to two lines). Every row loads independently, so one slow or broken service never blocks the others from updating. A row that keeps failing is asked less often (60, then 120, then 240 seconds between tries) until a pull-to-refresh asks it again.

Because a kept value can be old, Home’s System status banner tracks each health source’s last successful check separately. “Health checks are stale” or “Health checks unavailable” means one of them stopped answering; tap the banner to see which, and when it last did.

The request log

Settings → Diagnostics (Mac: Settings → Diagnostics → Open request log…) lists the last 500 requests since the app started: method, host and port, path, status or error, duration and size. Errors only, the host picker and the search field narrow it down, and Export as text shares it with the app version at the top. It is the quickest way to see which address a failing screen actually asks for, and what came back. Query strings, headers and bodies are never recorded, and path parts that look like a key are replaced with “…”. Downloads, players and artwork do not go through it.

Home shows the welcome screen

If Home shows the welcome screen (Look around first, Connect a service, Bring your configuration), no service has a URL (or key, for key-only groups) set yet. Connect one from there or from Settings → Services, or choose Look around first if you just want to see the app working before wiring up real credentials.

If Home says Choose your three services instead, your services are all there but paused: more than three are connected on the free plan and none has been chosen yet (see below).

Free plan: “0 of 3 services active”

The free plan runs up to three service groups at once. If you configure a fourth, the app never silently picks which three stay active, that decision is always yours. Instead every extra service shows “Paused · Free limit” (credentials kept, nothing hidden from the server), and Settings shows “Choose free services”.

Open Settings → Upgrade to Pro (or Choose free services, or Choose services on Home) and pick up to three. Each group counts once no matter how many screens it feeds: Nextcloud’s Files, Notes, Tasks, Contacts and Deck together are one slot, and so is Server (Glances + temperatures) or Money (Firefly III + Firefly Pico + subscriptions). Dashboard links (HOMEPAGE_URL) and disabled services never count towards the three.

qBittorrent locks you out after repeated failures

qBittorrent bans an IP for a period after five failed login attempts. Because of this, Pocket Homelab never attempts a login while QBIT_PASSWORD is empty, you’ll see “qBittorrent password not set, add QBIT_PASSWORD in Settings” instead of a failed login. Make sure the password is set correctly before testing repeatedly, and if you do get banned, wait it out on the qBittorrent side (or restart it, depending on your setup) rather than retrying from the app.

Kuma: status page slug vs. API key

Uptime Kuma can be read two different ways, and mixing them up is a common source of “why don’t I see monitor X”:

• A status page slug only shows monitors you’ve explicitly published to that page, but does give you groups and a 24-hour uptime percentage.
• An API key shows every monitor Kuma tracks, with no groups and no 24-hour uptime figure.

If both are set, the API key wins. See the Uptime Kuma page for the full comparison.

Backrest: “Overdue” and the grace period

A plan or repository going from Current to Overdue does not necessarily mean the backup failed, it means the time since the last success has passed the schedule’s normal interval plus BACKREST_GRACE_HOURS (2 hours by default). If your server sleeps, your network is slow, or a run just started a bit late, raising the grace period in Settings → Services → Backrest avoids false alarms without hiding a genuinely broken schedule. See Backrest for the full health-state logic.