Troubleshooting WebRTC Connections¶

This guide helps you diagnose and resolve common issues with WebRTC connections in FuryMesh.

Common Connection Issues¶

Unable to Establish Connection¶

If peers cannot establish a WebRTC connection:

1. Check Network Configuration:
2. Ensure both peers have internet connectivity
3. Verify that required ports are not blocked by firewalls

4. WebRTC typically uses UDP ports 1025-65535

5. STUN/TURN Server Issues:

6. Verify STUN servers are accessible
7. Consider adding TURN servers for difficult NAT scenarios

8. Update your configuration:

   webrtc:
     stun_servers:
       - "stun:stun.l.google.com:19302"
       - "stun:stun1.l.google.com:19302"
     turn_servers:
       - "turn:your-turn-server.com:3478"
     username: "your-username"  # For TURN
     credential: "your-password"  # For TURN
   

9. NAT Traversal Problems:

10. Some NAT configurations are challenging for WebRTC
11. If behind symmetric NAT, TURN servers are usually required
12. Check logs for ICE connectivity failures

Connection Drops Frequently¶

If connections are established but drop frequently:

1. Network Stability:
2. Check for network congestion or instability

3. Ensure sufficient bandwidth for transfers

4. Adjust Timeouts:

5. Increase ICE timeout for challenging networks:

   webrtc:
     ice_timeout: 60  # Increase from default 30 seconds
   

6. Check Resource Usage:

7. High CPU or memory usage can affect WebRTC stability
8. Reduce concurrent transfers if system is overloaded

Transfer Issues¶

Slow Transfer Speeds¶

If file transfers are slower than expected:

1. Adjust Chunk Size:
2. Larger chunks may improve throughput on stable connections
3. Smaller chunks work better on unstable connections

transfer:
  chunk_size: 2097152  # Increase to 2MB for faster networks

1. Increase Concurrent Chunks:
2. More concurrent transfers can improve throughput

transfer:
  max_concurrent_chunks: 10  # Increase from default 5

1. Network Limitations:
2. Check if your network has bandwidth limitations
3. WebRTC performance depends on the slowest peer's connection

Failed Transfers¶

If transfers fail to complete:

1. Increase Retry Attempts:

transfer:
  max_retries: 5  # Increase from default 3

1. Adjust Retry Interval:

transfer:
  retry_interval: 10s  # Increase from default 5s

1. Increase Idle Timeout:

transfer:
  idle_timeout: 60s  # Increase from default 30s

1. Check Logs for Specific Errors:
2. Look for timeout or connection errors
3. Check for chunk transfer failures

Debugging Tools¶

Enable Verbose Logging¶

Increase log verbosity to get more detailed information:

logging:
  level: "debug"  # Set to debug for more detailed logs
  webrtc_level: "debug"

Check Connection States¶

Monitor connection states in the logs:

• New: Connection created but not active
• Connecting: ICE negotiation in progress
• Connected: Connection established
• Disconnected: Temporarily disconnected
• Failed: Connection failed
• Closed: Connection closed

Monitor Transfer Statistics¶

Use the transfer statistics to diagnose issues:

stats, err := fileManager.GetTransferStats(fileID)
if err == nil {
    fmt.Printf("Transfer progress: %d/%d chunks\n", 
        stats.CompletedChunks, stats.TotalChunks)
    fmt.Printf("Transfer rate: %.2f KB/s\n", 
        stats.TransferRate / 1024)
}

Advanced Troubleshooting¶

WebRTC Signaling Issues¶

If signaling fails:

1. Check DHT connectivity
2. Verify that signaling messages are being exchanged
3. Look for errors in the signaling process

ICE Candidate Exchange Problems¶

If ICE candidates are not being exchanged properly:

1. Check for firewall or NAT issues
2. Verify STUN server connectivity
3. Consider using TURN servers as a fallback

Data Channel Problems¶

If data channels fail to open or send data:

1. Check for negotiation errors
2. Verify that both peers support the data channel configuration
3. Look for buffer overflow issues with large transfers

Getting Help¶

If you continue to experience issues:

1. Gather detailed logs with debug level enabled
2. Check the GitHub issues for similar problems
3. Provide detailed information when reporting issues:
4. Network configuration
5. FuryMesh version
6. Error messages and logs
7. Steps to reproduce the issue