Troubleshooting

Quick map from symptom to cause and fix.

Symptom Most likely cause Fix
Browser says the tunnel address does not exist (DNS error) The wildcard DNS record is missing See Getting started
Browser certificate warning on a tunnel subdomain The certificate does not cover the wildcard Get a cert valid for *.tunnels.example.com and tunnels.example.com — see Reverse proxy
Tunnel page shows an error page / 503 No such tunnel, or its agent is not connected Check the exact sub-domain spelling; then check the agent process on your machine
Agent logs in, immediately tries again, forever Wrong or revoked token, or wrong server address Re-copy the token from the panel (Tokens tab); check --url
Slow app endpoints time out, fast ones work An app behind the tunnel took too long to start responding The tunnel allows about a minute between the request and the first bytes of the answer; heavy jobs should return quickly and report later
Nobody can sign in to an Internal-protected tunnel The tunnel has no users/groups selected, or the visitor's IP is temporarily blocked Add at least one user or group in the tunnel's Authentication tab; check the Security page for blocked addresses
Panel logins (OIDC) gone after server restart Panel OIDC sessions are kept in memory by design Sign in again; consider basic/file if this annoys you
Tunnel logins (Internal) gone after server restart Internal visitor sessions are kept in memory by design Visitors sign in again; OIDC-protected tunnels survive restarts
Charts show "No stats yet" The agent just connected, or nothing is connected Measurements arrive every ~10 seconds; the charts display minute-sized buckets, so give it a minute

Details

DNS error on name.tunnels.example.com, but the panel opens. Tunnel addresses only work if your domain has a wildcard record pointing at the server — A (or AAAA/CNAME) record for *.tunnels.example.com with the same value as the base record. Add it at your DNS provider; propagation can take a while.

Agent keeps reconnecting. The agent retries forever on a fixed interval — that is normal while the network is down. Endless retries with "token" errors in the log mean the token was deleted in the panel (deleting a token disconnects its machines) or was never copied fully. Create a new token, stop the agent, start it with the new token.

503 with a tunnel that exists. The server answers 503 both when nothing is connected and when the sub-domain has no tunnel. Distinguish in the panel: the tunnel's Connected tab shows live connections. If it is empty, the agent on your machine is not running or cannot reach the server (/agent endpoint, Bearer token).

Blocked addresses. After several failed sign-in attempts on an Internal-protected tunnel, the visitor's IP is blocked for a while — they see the login page but cannot get in even with the right password. Unblock them on the Security page, or wait for expiry.

Before asking for help

Collect the following (remove passwords and tokens first):

  1. The exact serve command line (flags and values, minus secrets).
  2. The exact connect command line, token replaced with <token>.
  3. The server log lines around the problem.
  4. The agent log lines around the problem.
  5. What you saw in the browser: the address, the error text or status code.