Troubleshooting

If you’re experiencing issues with Porthole, check the following common scenarios.

503 Service Unavailable (Tunnel Not Connected)

A 503 Service Unavailable error typically means the relay server is reachable, but your local client is not currently connected to it.

Check CLI Status: Ensure the Porthole CLI is running and hasn’t disconnected.
Connection Stability: If your internet connection is unstable, the CLI will attempt to reconnect automatically. Check your terminal output for reconnection logs.
Valid Token: Ensure you are using a valid authentication token if required.

A 502 Bad Gateway error indicates that the Porthole client is connected to the relay, but it cannot reach the local service on your machine.

Service Running: Verify that your local web server (e.g., Node.js, Python, Docker) is actually running.
Correct Port: Ensure the port specified in the porthole command matches the port your local service is listening on.
Bind Address: Make sure your local service is binding to 127.0.0.1 or 0.0.0.0. If it only binds to a specific IP, the client might not be able to reach it.

Hot Module Replacement (HMR) and other WebSocket-based features require specific handling.

Protocol Support: Porthole supports WebSockets out of the box. Ensure your local server is configured to accept WebSocket connections.
HMR Configuration: Some frameworks (like Vite or Webpack) require you to specify the public H5 client URL or set the allowedHosts to include your tunnel URL.
Timeouts: Long-lived idle WebSocket connections might be closed by intermediate network layers. Implement heartbeats if possible.

If you recently changed your tunnel name or just started a new one, your browser or OS might cache the DNS record.

Flush DNS: Try flushing your DNS cache (ipconfig /flushdns on Windows, sudo killall -HUP mDNSResponder on macOS).
Incognito Mode: Test the URL in a private/incognito window to bypass browser-level caching.

If you’re still stuck, enable verbose logging to see detailed information about the connection and requests.

porthole 8000 --verbose

This will output detailed logs of every request being proxied and any connection-level events.

If the landing page stats show zeros, the stats API likely isn’t configured on your host.

Set these Vercel environment variables for the website:

Note: the personal API key must be a read key (starts with phx_), not the project ingest token.