Troubleshoot Turbotunnel

Diagnose gateway, local app, configuration, and deployment failures.

Find the symptom that matches your failure, apply the suggested check, and retry the command. Turbotunnel preserves saved configuration when deployment or gateway verification fails.

The local app is unavailable

tt http and tt dev start the tunnel without waiting for the local app. While the app is unavailable, the public URL returns an HTTP 502 page with recovery steps.

Start the app and confirm its port. If it listens on a different interface, pass that host:

tt http 5173 --host 127.0.0.1

If the app is running but forwarding still fails, compare its URL with the Local row. The command passed after tt dev -- must listen on the configured project port or --port value. Use tt http --host for servers on another interface.

No gateway is configured

Deploy a gateway:

tt deploy

For local gateway development, provide the domain, relay URL, and relay secret described in the tt http reference.

The Vercel CLI is missing or logged out

Install the Vercel CLI and authenticate:

npm i -g vercel
vercel login
vercel whoami

Then retry tt deploy.

A custom domain fails

Confirm that the active Vercel account can use the domain. Review the Vercel CLI output and complete any required Domain Name System (DNS) verification, then run tt deploy again.

Turbotunnel keeps your previous local configuration when deployment or verification fails.

Project configuration is invalid

Fix the reported fields in turbotunnel.json. Project configuration accepts only tunnel fields: port, slug, domain, access, and projects for named-project configurations.

Saved gateway configuration is invalid

Fix the JavaScript Object Notation (JSON) in ~/.turbotunnel/config.json. If you remove the file, you must run tt deploy again to recreate the saved gateway settings.

A public request fails

Use the response status to identify where the request failed:

• 413: the request body exceeded 4 MiB, and the gateway did not contact the local app
• 502: the local request failed, timed out, or returned a body larger than 4 MiB
• 504: the gateway did not receive a response within 30s; the local app may have received the request

See Turbotunnel limits for the complete limits and scopes.

A public WebSocket closes

Use the close code to narrow the cause:

Gateway verification fails

Request the gateway status as JSON, then inspect the Vercel deployment logs:

curl -H 'Accept: application/json' \
  https://gateway.example.com/_turbotunnel/status

The saved configuration changes only after verification passes.