Tunnel Error Reference
Every error you can hit on a PreviewBox tunnel URL, with a stable code you can search for. Each entry tells you exactly what happened, how to fix it if you run the tunnel, and the one line to relay if you are just visiting.
12 of 12 errors
No PreviewBox tunnel exists at this address. The tunnel may have been deleted, renamed, or the URL may contain a typo.
- Share the exact URL PreviewBox printed after starting — not the port number.
- If you deleted or renamed the tunnel, create a new one and update the link you sent out.
“I opened the PreviewBox tunnel and got "Tunnel Not Found" (PB-1404).”
The subdomain itself is malformed. Tunnel names are lowercase letters, numbers and hyphens, like my-app.previewbox.dev.
- Hand out the exact URL PreviewBox printed, not a hand-typed address.
- Custom subdomains must be alphanumeric plus hyphens — no spaces or special characters.
“I tried to open the PreviewBox tunnel and it said the address was invalid (PB-1405).”
This address exists but is not currently active. The CLI either was not started or has disconnected.
- Start it with: prevbox serve http <port> --subdomain <name>
- A long-running laptop or session may have gone to sleep — restart the tunnel.
“The PreviewBox tunnel went offline and the site won’t load (PB-1502). Can you restart it?”
The tunnel has an IP allowlist and the visitor’s address is not on it. Only approved IPs can open this page.
- Add the visitor’s IP address to the tunnel’s allowlist, or disable the allowlist temporarily.
- Find it under Dashboard → the tunnel → IP restrictions.
“I got "Access Denied" (PB-1503) on the PreviewBox tunnel — my IP may need to be added to the allowlist.”
The tunnel is connected, but the local app it points to refused the connection. The app is not running, is on another port, or crashed.
- Confirm your app is actually running (check your terminal).
- Make sure it is listening on the exact port the tunnel was started with.
- A port or socket conflict can cause this — change the app port and restart both.
“The PreviewBox tunnel showed "Server Unreachable" (PB-2502) — the app behind the tunnel isn't running.”
The tunnel is connected, but the local app did not answer in time. The app may be hung, slow, or overwhelmed.
- Your app may be hung or blocked — restart it and the tunnel.
- Large or slow responses can exceed the tunnel’s timeout. Check the app’s response time.
“The PreviewBox tunnel timed out loading (PB-2503) — the app behind it may have hung. Mind restarting it?”
PreviewBox received a request it could not parse. Usually a broken or hand-built link, not your setup.
- Check the exact URL that failed — a hand-written link may be malformed.
- If an app generates this link, it may be building URLs incorrectly.
“I hit "Bad Request" (PB-1400) on the PreviewBox tunnel — may be a broken link.”
The request exceeded PreviewBox’s 10MB body limit. Large uploads and multi-megabyte payloads will fail.
- The 10MB limit is fixed — large uploads will always fail.
- Consider chunked uploads or a different endpoint for big files.
“The PreviewBox tunnel rejected a request as too large (PB-2413) — the payload is over 10MB.”
The tunnel hit an unexpected error while forwarding the request. Usually transient — a brief network hiccup between the CLI and PreviewBox.
- This can be a brief network hiccup between you and PreviewBox — try again.
- Restart the tunnel if it recurs, and check the prevbox logs for errors.
“I hit a generic "Tunnel Error" (PB-2501) on the PreviewBox link — a refresh may fix it.”
PreviewBox rate limited the tunnel because there were too many requests or connection attempts in a short window.
- New tunnel connections are rate limited per minute by default.
- The per-tunnel rate limit is configurable in the dashboard.
“The PreviewBox tunnel said "Too Many Requests" (PB-2604) — I’ll retry in a moment.”
PreviewBox gave up waiting for the tunnel to respond. The app took too long to reply within the tunnel’s request timeout.
- Your app took too long to respond to the tunnel.
- Tunnels have a hard request timeout — slow endpoints will fail it.
“The PreviewBox tunnel timed out waiting for the app (PB-2608) and didn't load.”
PreviewBox’s connection to the tunnel was lost mid-request. The CLI’s WebSocket to PreviewBox disconnected.
- Your tunnel’s WebSocket to PreviewBox disconnected during a request.
- Restart the tunnel to re-establish the connection cleanly.
“The PreviewBox tunnel dropped the connection mid-load (PB-2609) — a refresh may fix it.”
The code for any error also appears in the X-Error-Code response header, so scripts and integrations can match it programmatically. Still stuck? See HTTP Tunnels, TCP Tunnels, or the CLI reference.