Troubleshooting

Common issues and how to resolve them. Click a problem to expand the solution.

Connection issues

“Connection refused”

Cause: Local service is not running or listening on the wrong port.

Solution:

1. Verify your service is running: curl http://localhost:8080
2. Check the port matches your --service flag
3. Check firewall rules aren’t blocking localhost

WebSocket connection fails

Cause: Network connectivity issue or relay server is down.

Solution:

1. Check your internet connection
2. Check hle.world is reachable from your browser
3. Check firewall allows outbound WebSocket (WSS) connections on port 443

“Rate limit exceeded” (WS close code 4008)

Cause: The client sent far more control messages per second than the relay accepts, and kept it up for about half a minute, so the relay disconnected it to protect shared resources.

Solution:

1. This is almost always a bugged or misconfigured client, not normal traffic — check the client logs for a message loop
2. Update to the latest hle client version
3. If it persists, open an issue with the client version and what your local service is

Authentication issues

“Invalid API key” (WS close code 4001)

Cause: API key is missing, invalid, or inactive.

Solution:

1. Verify key exists in dashboard: hle.world/dashboard/keys
2. Copy the raw key from dashboard (shown only once at creation)
3. Pass it with --api-key flag or save to ~/.config/hle/config.toml
4. Check key is active (not deleted or disabled)

“Tunnel limit exceeded” (WS close code 4003)

Cause: You’ve reached the tunnel limit for your API key.

Solution:

1. Check dashboard for active tunnels
2. Delete unused tunnels (by disconnecting the client)
3. Or delete the old API key and create a new one with higher max_tunnels

Dashboard login fails

Cause: Wrong email/password, rate limit, or SSO misconfiguration.

Solution:

1. Double-check email and password
2. If you see rate limit error, wait 5 minutes before retrying
3. Try SSO (GitHub or Google) instead of email/password
4. Clear browser cookies and try again

Access and routing issues

“502 Bad Gateway”

Cause: No tunnel client is connected for this subdomain.

Solution:

1. Check client is running: hle tunnel create http://localhost:8080
2. Verify client API key is correct and active
3. Check client is connecting to the right relay server
4. Check client logs for errors

“404 Not Found” or “Cannot GET /”

Cause: Your local service is returning 404.

Solution:

1. Test local service directly: curl http://localhost:8080/
2. Verify your service is running and responding
3. Check the path you’re accessing (your service may require a prefix like /api)

WebSocket doesn’t work through tunnel

Cause: WebSocket proxying is disabled or your service doesn’t support WebSocket.

Solution:

1. Verify you’re using --websocket flag (default enabled)
2. Check your service supports WebSocket on the same port as HTTP
3. Test WebSocket locally: Many dev tools have WebSocket inspectors

Localhost development

Wildcard DNS doesn’t work on localhost

Cause: Localhost doesn’t have wildcard DNS configured.

Solution: Use the query parameter fallback:

http://localhost:8000/?_hle_subdomain=myapp-x7k

Performance and stability

High latency or slow responses

Cause: Network congestion, distant relay server, or slow local service.

Solution:

1. Check your internet connection bandwidth
2. Check latency to hle.world from your location
3. Profile your local service to ensure it’s responsive

Client disconnects frequently

Cause: Network instability or firewall timeout.

Solution:

1. Check your network connection
2. Check firewall isn’t closing idle WebSocket connections
3. Enable debug logging: hle tunnel create ... --debug
4. Check server logs for errors

Getting help

• Documentation: hle.world/docs
• GitHub Issues: github.com/hle-world/hle-client/issues
• Debug logging: Run client with --debug and share logs