Troubleshooting

Resolve common InstaTunnel issues quickly with these troubleshooting guides and solutions.

🔌 Connection Issues

Tunnel Won't Start

❌ Error: Failed to connect to tunnel server

Check Your Internet Connection

# Test connectivity

$ ping instatunnel.my

$ curl -I https://api.instatunnel.my/health

Verify API Key

# Check API key format

$ instatunnel config show

# Test authentication

$ instatunnel auth test

Firewall & Proxy Issues

# Try different connection method

$ instatunnel 3000 --connection-type http

# Use proxy if needed

$ instatunnel 3000 --proxy http://proxy.company.com:8080

Tunnel Disconnects Frequently

Enable Auto-Restart

$ instatunnel 3000 --auto-restart --retry-interval 5s

Increase Keep-Alive

$ instatunnel 3000 --keep-alive 60s --timeout 120s

Switch Regions

$ instatunnel 3000 --region us-west # Try different region

Slow Performance

Enable Compression

$ instatunnel 3000 --compress --connections 10

Optimize Local App

• Ensure your local app responds quickly (<100ms)
• Check for slow database queries or API calls
• Use local caching when possible
• Minimize large file transfers

🚪 Port & Application Issues

Port Already in Use

❌ Error: Port 3000 is already in use

Find What's Using the Port

# On macOS/Linux

$ lsof -i :3000

# On Windows

$ netstat -ano | findstr :3000

Use a Different Port

$ instatunnel 3001 # Try next available port

$ instatunnel 8000 # Or use common alternative

Auto-Detect Available Port

$ instatunnel --auto-port # Automatically find free port

App Not Responding

❌ Error: Connection refused to localhost:3000

Verify App is Running

# Test local access

$ curl http://localhost:3000

# Check if port is listening

$ telnet localhost 3000

Check App Configuration

• Ensure app binds to 0.0.0.0 or localhost, not 127.0.0.1 only
• Check if CORS is properly configured
• Verify no authentication blocking local requests
• Look for firewall rules blocking local connections

🔐 Authentication & Permission Issues

Invalid API Key

❌ Error: Invalid or expired API key

Get a New API Key

# Login and get new key

$ instatunnel login

# Or visit dashboard

$ open https://dashboard.instatunnel.my/api-keys

Set API Key Correctly

# Environment variable

$ export INSTATUNNEL_API_KEY="it_1234567890abcdef"

# Or config file

$ instatunnel config set api_key it_1234567890abcdef

Subdomain Already Reserved

❌ Error: Subdomain 'myapp' is reserved by another user

Try Alternative Names

$ instatunnel 3000 --subdomain myapp-dev

$ instatunnel 3000 --subdomain myapp-2024

$ instatunnel 3000 --subdomain mycompany-myapp

Use Auto-Suffix

$ instatunnel 3000 --subdomain myapp --auto-suffix

✅ Tunnel created: https://myapp-2.instatunnel.my

🌐 Browser & HTTPS Issues

Mixed Content Warnings

Ensure Local App Uses HTTPS

# For development servers that support HTTPS

$ npm start -- --https # React

$ ng serve --ssl # Angular

Force HTTPS Forwarding

$ instatunnel 3000 --force-https

CORS Issues

Configure Your App for Tunneling

// Express.js example

app.use(cors({

origin: [

'http://localhost:3000',

'https://*.instatunnel.my'

]

}))

Use Tunnel Headers

# Add custom headers for CORS

$ instatunnel 3000 --header "X-Tunnel-Origin: true"

🛠 Advanced Troubleshooting

Debug Mode

# Enable verbose debugging

$ instatunnel 3000 --log-level debug --verbose

🔍 WebSocket connection established

🔍 Tunnel registered: abc123.instatunnel.my

🔍 Health check: OK

🔍 Request: GET / from 203.0.113.1

🔍 Response: 200 (45ms)

Generate Support Bundle

# Create diagnostic bundle

$ instatunnel support-bundle

✅ Support bundle created: instatunnel-debug-20240702.zip

📊 Included:

- Configuration files

- Recent logs

- Network connectivity tests

- System information

Health Checks

# Run comprehensive health check

$ instatunnel doctor

🔍 Running InstaTunnel diagnostics...

✅ Internet connectivity: OK

✅ DNS resolution: OK

✅ API server reachable: OK

✅ Authentication: OK

⚠️ Local app on port 3000: Not responding

✅ WebSocket support: OK

📞 Getting Help

Community Support

• Discord: Real-time chat with community
• GitHub Issues: Report bugs and feature requests
• Stack Overflow: Tag questions with 'instatunnel'
• Reddit: r/instatunnel community

Premium Support

• Email Support: support@instatunnel.my
• Priority Queue: Pro/Business users
• Live Chat: Available in dashboard
• Video Calls: Business tier scheduled support

🚀 Quick Fix: 90% of issues are resolved by running instatunnel doctor and following the suggested fixes. Always try this first!

Where should I start in InstaTunnel docs?

Evidence and trust

Release cadence

Security controls

Reliability runbooks

Documentation