Common errors
The error messages you are most likely to see from the JustTunnel CLI, what each one means, and how to fix it.
This page lists the error strings you are most likely to hit, in the exact form the CLI prints them. If you searched here for the error you are seeing and didn't find it, scroll to Still stuck? at the bottom.
could not reach justtunnel server
What it means. The CLI tried to talk to the JustTunnel API (for auth login, auth verify, or starting a tunnel) and the HTTP request failed before the server responded. This is almost always local network — DNS, captive portal, corporate proxy, or you're offline.
How to fix.
- Confirm you're online:
curl https://justtunnel.com. - If you're on a corporate network, check whether outbound HTTPS to
justtunnel.comis allowed. - If you set a custom server URL with
justtunnel auth --server, double-check it points somewhere real.
invalid API key
What it means. The CLI sent your API key to the server's verify endpoint and the server rejected it (HTTP 401). Either the key was rotated in the dashboard, your account was suspended, or the value in ~/.justtunnel/config.yaml is corrupted.
How to fix.
justtunnel logout
justtunnel authThat clears the stored key and runs the device-auth flow to mint a new one.
server returned 403: ... (with the hint "This is not an authentication problem")
What it means. You authenticated successfully, but the server refused to start the tunnel. The CLI deliberately steers you away from re-running justtunnel auth here because re-auth will not fix it. The three common causes are:
- The subdomain you requested requires the Pro plan (free and starter don't get reserved subdomains).
- The subdomain is already in use by another connected tunnel.
- Your account or team is suspended.
How to fix. See Subdomain conflict for the subdomain cases. For plan-tier issues, see Plans and limits. For suspension, contact support (link at the bottom of this page).
See also: Subdomains, Plans and limits
server returned 4xx: TUNNEL_LIMIT_REACHED
What it means. Your plan caps the number of concurrent tunnels and you're at the cap. The server message includes the exact number — for example, Free plan limited to 1 tunnel. Upgrade to Starter for ....
How to fix.
- Stop a tunnel you're not using (
Ctrl+Cin the terminal running it). - Or upgrade your plan — see Upgrade and downgrade.
See also: Plans and limits
server returned 4xx: PLAN_LIMIT_REACHED
What it means. You hit a per-plan feature cap. The most common case is password-protected tunnels — Free allows one at a time, Starter allows two, and Pro lifts the cap. The server message names the specific limit you hit.
How to fix. Stop another tunnel that's holding the same resource, or upgrade the plan.
See also: Password protection, Plans and limits
server returned 4xx: RESERVED_SUBDOMAIN_NOT_ALLOWED
What it means. You asked for a specific subdomain (with --subdomain or via tunnels.yaml) and your plan doesn't include reserved subdomains. Free and Starter get random subdomains only; reserved names are a Pro feature.
How to fix. Drop the --subdomain flag to take a random name, or upgrade to Pro and reserve the name in the dashboard.
See also: Subdomains, Reserve a subdomain
target unreachable / <host>:<port> is not reachable
What it means. A request hit your tunnel URL, the server forwarded it to your CLI, and the CLI tried to proxy it to your local target — but the local connection failed. The local server isn't running, isn't listening on the port you told the CLI, or isn't binding to a reachable interface.
How to fix. See the dedicated page: Local target unreachable.
See also: Tunnel anatomy
tunnel client timeout (HTTP 504 from the proxy)
What it means. The server forwarded a request to your CLI but didn't get a response in time. Usually your local handler is slow (long DB query, blocking call) or hung. The default per-request timeout is 30 seconds; you can raise it with --local-timeout.
How to fix.
justtunnel 8080 --local-timeout 120sIf the local handler hangs forever, fix the handler — raising the timeout just delays the same failure.
See also: Local timeout
request body too large / upstream response too large (HTTP 502)
What it means. The proxy enforces a body size cap (10 MB) in both directions. A request body or a response body crossed the limit and was rejected.
How to fix. JustTunnel is built for HTTP webhooks and dev traffic, not large-file transfer. Move large uploads off the tunnel (S3, signed URL, direct upload) and use the tunnel for the API calls that initiate them.
polling too fast
What it means. During the device-auth flow, the CLI polled the server's verify endpoint faster than the rate the server set. This is rare in normal use; usually it means you have multiple justtunnel auth flows racing.
How to fix. Cancel any other running justtunnel auth commands and try again.
See also: auth
local config write failed; rolled back server-side create
What it means. You ran justtunnel worker install (or worker create). The server created the worker record successfully, but writing the matching config to ~/.justtunnel/workers/ failed — usually a disk-full or permissions issue. The CLI rolled back the server side so you don't end up with a phantom worker.
How to fix. Fix the local disk or permission problem and re-run the command.
See also: Worker tunnels, Worker won't start
bootstrap supervisor for "..." failed
What it means. justtunnel worker install registered the worker on the server and wrote the local config, but the OS service manager (launchd on macOS, systemd --user on Linux) refused to register the unit.
How to fix. See Worker won't start for the platform-specific recovery steps. The CLI's hint — "retry with justtunnel worker install <name> or justtunnel worker uninstall <name> to roll back" — is the right starting point.
See also: Worker tunnels
connection replaced during request handling
What it means. A request was being proxied when the WebSocket reconnected (because the previous one dropped). The in-flight response is dropped — the caller will see a 502 or a network error and is expected to retry.
How to fix. Nothing on your side. This is normal during brief network interruptions. If you see it constantly, see Disconnects and reconnects.
Still stuck?
If your error isn't here, open an issue with the exact error string and the command you ran. We add entries to this page based on what shows up in real reports.