Fehlerbehebung

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

Connection and access errors

426 Upgrade Required: Anonymous tunnels require CLI 1.1.24 or newer. Run npm install -g instatunnel@latest and restart the tunnel.
401 on tunnel connection: Use the API key for the account that owns the tunnel. For anonymous use, start a new random tunnel with the updated CLI; it handles the private connection token automatically.
409 on tunnel connection: Another CLI is already connected. Stop that session before reconnecting; new clients do not replace it.
401 for visitors: A Pro/Business protected tunnel requires the browser password form, X-InstaTunnel-Password for API clients, or HTTP Basic Auth when configured.

For webhook providers that cannot send the required auth header, use an unprotected endpoint and verify the provider signature in your app. See the full troubleshooting matrix.

🔌 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!

Wo sollte ich in der InstaTunnel-Dokumentation starten?

Evidenz und Vertrauen

Release-Kadenz

Sicherheitskontrollen

Zuverlassigkeits-Runbooks

Dokumentation