Guide
Find out why a tunnel is not working
Find which part of the path from the internet to your app is failing, and what to do about it.
- Applies to
- All plans; durable tunnels
- Time
- About 3 minutes
- What it changes
- Sends one GET request to the tunnel's address. It changes nothing.
- Last reviewed
- , by Product documentation
Before you begin
What to know before you start
- Tunnel Doctor sends one request to the tunnel's public address. It sends no credentials, follows no redirects, and keeps only the status and the relay's code.
- The request is sent from the InstaWormhole edge, so it is not an independent outside check.
Steps
Step 1. Open the tunnel in the dashboard and choose Run Tunnel Doctor.
You should see: The button changes to Checking every layer, then the result appears.
Step 2. Read the overall result.
Overall results Result What it means Working: a request through the public address reached your app Every layer passed. Working, with something to look at The tunnel works and one layer has a warning. Not working A layer failed. Fix the first failing layer. Checked up to the password prompt The tunnel has a password, so the check stopped at the prompt. This is expected. You should see: You know whether to fix something or to look at a warning.
Step 3. Start with the first layer marked as failing, and follow its instruction.
The layers run in the order a request travels:
- Address lookup (DNS)
- Secure connection (TLS)
- Tunnel state
- Connector
- Access protection
- Your app
- Request through the public address
Each finding has a diagnostic code. Look the code up in the reference for what it means and who can fix it.
You should see: You have one specific thing to change.
Step 4. Run Tunnel Doctor again after you fix it.
You should see: The layer you fixed shows as passing.
To check: Your app receives the check in an X-Instawormhole-Diagnostic header, so its logs show the request.
You are done when
- The overall result says Working, or it names the first layer that failed and what to do.
What to do next
Undo or clean up
- None. Tunnel Doctor stores nothing.
Good to know
Tunnel Doctor also recognises common development-server problems, such as a Vite or Next.js server refusing the tunnel's address, and shows the exact line to add with your address filled in.
Related
This page is part of Diagnose and fix. Still stuck? Contact support.