Troubleshooting

Most problems come down to the local app, not the tunnel. Start with these checks.

502 or "connection refused"

The tunnel is up but nothing is listening on the port you gave it. Start your app first, confirm the port, then start the tunnel.

# Is anything listening on the port?lsof -i :3000# Start your app first, then the tunnelnpm run devrl-tunnel http 3000

"Blocked request. This host is not allowed"

Vite and some dev servers reject unknown hosts. The CLI already avoids this: by default it sends your app the local host (for example localhost:3000), and the public host goes in X-Forwarded-Host. Redirects to the local host are rewritten back to the public URL. You only see this error if you use --preserve-host; in that case allow the tunnel domain:

Blocked request. This host ("dev-xyz.t.resolvelabs.com.br") is not allowed.

// vite.config.tsexport default defineConfig({  server: { allowedHosts: [".t.resolvelabs.com.br"] },});

"Subdomain not reserved" or already taken

--subdomain only accepts names reserved in your account. Reserve it in the dashboard (names are unique across accounts) and log in with rl-tunnel auth login. Run rl-tunnel whoami to see what your account has.

"Limit of simultaneous tunnels reached"

An account allows 10 simultaneous tunnels. Close tunnels you no longer use (Ctrl+C). After a network drop the old session can take up to half a minute to be released, and the CLI retries by itself.

"Invalid or revoked token"

The token was revoked in the dashboard or mistyped. Create a new one, or run rl-tunnel auth login again. Check for an old RL_TUNNEL_TOKEN in your environment: it takes priority over the saved login.

The browser doesn't open on login

Use rl-tunnel auth login --no-browser, open the printed URL on any device and confirm the code.

The app shows the wrong site or redirects to localhost

Your app may build absolute URLs from the Host header or an environment variable. Use --host-header, or set the public URL (for example APP_URL) to the tunnel address.

Still stuck?

Run with --debug to see connection details, and include the output when you contact support.

rl-tunnel http 3000 --debug