Troubleshooting Tunnels

Connection Issues

”Connection Failed”

Symptoms: Tunnel won’t connect, shows error state.

Causes & Solutions:

1. Server unreachable

   • Verify server URL: curl https://api.yourdomain.com/health
   • Check your internet connection
   • Ensure server is running: docker compose ps

2. Invalid API key

   • Create a new API key in Settings → Account
   • Ensure the key is copied completely

3. Firewall blocking

   • Allow outbound HTTPS (port 443)
   • Check corporate firewall rules

”Authentication Failed”

Symptoms: Connects but fails during auth.

Solutions:

• Verify API key is correct
• Check API key hasn’t been revoked
• Try creating a new API key

”Subdomain Unavailable”

Symptoms: Can’t use desired subdomain.

Causes:

• Subdomain is reserved by the system
• Another user has an active tunnel with that subdomain
• Invalid subdomain format

Solutions:

• Choose a different subdomain
• Check subdomain follows naming rules (lowercase, no special chars)

Request Issues

502 Bad Gateway

Symptoms: Visitors see 502 error.

Causes & Solutions:

1. Local server not running

   • Start your dev server
   • Verify it’s listening on the expected port

2. Wrong port exposed

   • Check which port your server uses
   • Update the tunnel to use the correct port

3. Server crashed

   • Check server logs
   • Restart the server

504 Gateway Timeout

Symptoms: Requests timeout after ~30 seconds.

Causes & Solutions:

1. Slow local server

   • Check server performance
   • Look for blocking operations

2. Network latency

   • Test local server directly
   • Check VPS location and latency

Requests Not Reaching Server

Symptoms: No requests appear in logs.

Solutions:

1. Verify tunnel shows “Connected” status
2. Check you’re using the correct URL
3. Ensure HTTPS (not HTTP)
4. Clear browser cache

Performance Issues

Slow Responses

Possible causes:

• High latency to VPS
• Large response bodies
• Slow local server

Solutions:

• Choose a VPS closer to your location
• Optimize local server performance
• Enable compression if supported

High Latency

Diagnosis:

# Test latency to your server
ping api.yourdomain.com

# Test full request
time curl https://myapp.expose.yourdomain.com

Solutions:

• Use a VPS in your region
• Check for network congestion
• Minimize response sizes

WebSocket Issues

WebSocket Won’t Connect

Solutions:

1. Verify local server supports WebSocket
2. Check WebSocket path is correct
3. Ensure local server is accepting upgrades

Frequent Disconnections

Solutions:

1. Implement reconnection logic in client
2. Check for network instability
3. Increase server timeout settings

Debugging

Enable Verbose Logging

In the app:

1. Go to Settings → Advanced
2. Enable “Debug Logging”
3. View logs in Console.app

Check Server Logs

docker compose logs -f expose-server | grep tunnel

Test Locally First

Always verify your server works without the tunnel:

# Test local server
curl http://localhost:3000

# Then test through tunnel
curl https://myapp.expose.yourdomain.com

Getting Help

If you can’t resolve the issue:

1. Check GitHub Issues
2. Include in bug reports:
   • macOS version
   • App version
   • Error messages
   • Steps to reproduce