Stop WebRTC Connection Failures: A Developer's Guide

Introduction

WebRTC enables real-time peer-to-peer communication, but connection failures are frustratingly common. Whether you're building video conferencing, live streaming, or data channels, understanding the failure modes and their solutions is critical. This guide walks you through the most common issues, their root causes, and practical code solutions.

---

1. ICE Candidate Gathering Failures

Problem

Your peers can't find each other. The connection hangs indefinitely, or you see connectionState: 'failed' in the browser console.

Cause

ICE (Interactive Connectivity Establishment) candidates aren't being gathered or exchanged properly. This happens when:

• STUN/TURN servers are unreachable or misconfigured
• Firewall/NAT blocks UDP traffic
• Candidates aren't being signaled between peers
• Browser doesn't have permission to access network interfaces

Solution

// Configure ICE servers properly
const iceServers = [
  {
    urls: ['stun:stun.l.google.com:19302', 'stun:stun1.l.google.com:19302']
  },
  {
    urls: 'turn:your-turn-server.com:3478',
    username: 'user',
    credential: 'pass',
    credentialType: 'password'
  }
];

const peerConnection = new RTCPeerConnection({
  iceServers: iceServers,
  iceCandidatePoolSize: 10
});

// Listen for ICE candidates
peerConnection.onicecandidate = (event) => {
  if (event.candidate) {
    console.log('New ICE candidate:', event.candidate);
    // Send to signaling server
    signalingServer.send({
      type: 'ice-candidate',
      candidate: event.candidate
    });
  } else {
    console.log('ICE gathering complete');
  }
};

// Handle incoming ICE candidates
signalingServer.on('ice-candidate', async (data) => {
  try {
    await peerConnection.addIceCandidate(new RTCIceCandidate(data.candidate));
  } catch (error) {
    console.error('Failed to add ICE candidate:', error);
  }
});

// Monitor connection state
peerConnection.onconnectionstatechange = () => {
  console.log('Connection state:', peerConnection.connectionState);
  if (peerConnection.connectionState === 'failed') {
    console.error('Connection failed - attempting restart');
    peerConnection.restartIce();
  }
};

Tips

• Always use TURN servers for production. STUN alone fails behind symmetric NATs.
• Test your TURN server: turnutils_uclient -v -u user -w pass your-turn-server.com
• Set iceCandidatePoolSize to pre-gather candidates before offer/answer exchange
• Monitor iceGatheringState to detect gathering failures early

---

2. Offer/Answer Negotiation Failures

Problem

setLocalDescription() or setRemoteDescription() throws errors. Peers have incompatible codecs or malformed SDP.

Cause

• SDP (Session Description Protocol) is malformed or incomplete
• Codec mismatch between peers
• Attempting to set descriptions in wrong order
• Race conditions in simultaneous offer creation

Solution

// Proper offer/answer flow with error handling
async function createAndSendOffer() {
  try {
    // Create offer
    const offer = await peerConnection.createOffer({
      offerToReceiveAudio: true,
      offerToReceiveVideo: true
    });

    // Validate SDP
    if (!offer.sdp || offer.sdp.length === 0) {
      throw new Error('Empty SDP generated');
    }

    // Set local description
    await peerConnection.setLocalDescription(offer);
    console.log('Offer created:', offer.sdp);

    // Send to peer via signaling
    signalingServer.send({
      type: 'offer',
      sdp: offer.sdp
    });
  } catch (error) {
    console.error('Offer creation failed:', error);
  }
}

// Handle incoming offer
signalingServer.on('offer', async (data) => {
  try {
    // Prevent race condition
    if (peerConnection.signalingState !== 'stable') {
      console.warn('Signaling state not stable, queueing offer');
      return;
    }

    // Set remote description
    const offer = new RTCSessionDescription({
      type: 'offer',
      sdp: data.sdp
    });
    await peerConnection.setRemoteDescription(offer);

    // Create and send answer
    const answer = await peerConnection.createAnswer();
    await peerConnection.setLocalDescription(answer);

    signalingServer.send({
      type: 'answer',
      sdp: answer.sdp
    });
  } catch (error) {
    console.error('Offer handling failed:', error);
  }
});

// Handle incoming answer
signalingServer.on('answer', async (data) => {
  try {
    const answer = new RTCSessionDescription({
      type: 'answer',
      sdp: data.sdp
    });
    await peerConnection.setRemoteDescription(answer);
  } catch (error) {
    console.error('Answer handling failed:', error);
  }
});

Tips

• Always check signalingState before setting descriptions
• Use RTCSessionDescription constructor for validation
• Log SDP for debugging: console.log(peerConnection.localDescription.sdp)
• Implement a signaling queue for race condition prevention

---

3. Media Stream Failures

Problem

getUserMedia() fails or returns empty streams. Video/audio doesn't flow even after connection succeeds.

Cause

• User denies permission
• Device not available or in use
• Browser doesn't support requested constraints
• Tracks not added to peer connection

Solution

// Robust getUserMedia with fallback constraints
async function getMediaStream() {
  const constraints = {
    audio: {
      echoCancellation: true,
      noiseSuppression: true,
      autoGainControl: true
    },
    video: {
      width: { ideal: 1280 },
      height: { ideal: 720 },
      facingMode: 'user'
    }
  };

  try {
    const stream = await navigator.mediaDevices.getUserMedia(constraints);
    console.log('Media stream obtained:', stream);
    return stream;
  } catch (error) {
    console.error('getUserMedia failed:', error.name);

    // Fallback: try without video constraints
    if (error.name === 'OverconstrainedError') {
      try {
        return await navigator.mediaDevices.getUserMedia({
          audio: true,
          video: true
        });
      } catch (fallbackError) {
        console.error('Fallback failed:', fallbackError);
        throw fallbackError;
      }
    }
    throw error;
  }
}

// Add tracks to peer connection
async function addMediaToPeerConnection(stream) {
  stream.getTracks().forEach((track) => {
    peerConnection.addTrack(track, stream);
    console.log(`Added ${track.kind} track:`, track.label);

    // Monitor track state
    track.onended = () => {
      console.warn(`${track.kind} track ended`);
    };
  });
}

// Handle incoming remote streams
peerConnection.ontrack = (event) => {
  console.log('Remote track received:', event.track.kind);
  const remoteStream = event.streams[0];

  if (event.track.kind === 'video') {
    const videoElement = document.getElementById('remote-video');
    videoElement.srcObject = remoteStream;
  } else if (event.track.kind === 'audio') {
    const audioElement = document.getElementById('remote-audio');
    audioElement.srcObject = remoteStream;
  }
};

// Monitor track state changes
peerConnection.ontrack = (event) => {
  event.track.onmute = () => console.warn('Track muted');
  event.track.onunmute = () => console.log('Track unmuted');
};

Tips

• Always request permissions before creating peer connection
• Test device availability: navigator.mediaDevices.enumerateDevices()
• Use ontrack event, not onaddstream (deprecated)
• Handle permission denial gracefully with UI feedback

---

4. Data Channel Failures

Problem

Data channel opens but messages don't arrive, or channel never opens.

Cause

• Channel created before connection established
• Buffering issues with large messages
• Incorrect channel configuration
• Peer connection not ready

Solution

// Create data channel safely
function createDataChannel() {
  if (peerConnection.connectionState !== 'connected') {
    console.warn('Peer connection not ready');
    return;
  }

  const dataChannel = peerConnection.createDataChannel('data', {
    ordered: true,
    maxRetransmits: 3
  });

  setupDataChannel(dataChannel);
}

// Setup data channel handlers
function setupDataChannel(dataChannel) {
  dataChannel.onopen = () => {
    console.log('Data channel opened');
    dataChannel.send('Hello from initiator');
  };

  dataChannel.onmessage = (event) => {
    console.log('Message received:', event.data);
  };

  dataChannel.onerror = (error) => {
    console.error('Data channel error:', error);
  };

  dataChannel.onclose = () => {
    console.log('Data channel closed');
  };
}

// Handle incoming data channel (responder)
peerConnection.ondatachannel = (event) => {
  console.log('Data channel received');
  setupDataChannel(event.channel);
};

// Send large messages with buffering awareness
function sendLargeMessage(dataChannel, message) {
  const chunkSize = 16384; // 16KB chunks
  const chunks = [];

  for (let i = 0; i < message.length; i += chunkSize) {
    chunks.push(message.slice(i, i + chunkSize));
  }

  let index = 0;

  function sendChunk() {
    if (index < chunks.length) {
      if (dataChannel.bufferedAmount > 65536) {
        // Wait if buffer is full
        setTimeout(sendChunk, 100);
      } else {
        dataChannel.send(chunks[index++]);
        sendChunk();
      }
    }
  }

  sendChunk();
}

Tips

• Create data channels only after connection is established
• Monitor bufferedAmount to avoid overwhelming the channel
• Use ordered: true for message ordering guarantees
• Set maxRetransmits for reliability vs. latency tradeoff

---

5. Connection State Monitoring

Problem

You don't know when connections fail or recover.

Solution

// Comprehensive connection monitoring
function monitorConnection(peerConnection) {
  const states = {
    connectionState: peerConnection.connectionState,
    iceConnectionState: peerConnection.iceConnectionState,
    iceGatheringState: peerConnection.iceGatheringState,
    signalingState: peerConnection.signalingState
  };

  peerConnection.onconnectionstatechange = () => {
    console.log('Connection state:', peerConnection.connectionState);
    if (peerConnection.connectionState === 'failed') {
      handleConnectionFailure();
    }
  };

  peerConnection.oniceconnectionstatechange = () => {
    console.log('ICE connection state:', peerConnection.iceConnectionState);
  };

  peerConnection.onicegatheringstatechange = () => {
    console.log('ICE gathering state:', peerConnection.iceGatheringState);
  };

  // Log stats periodically
  setInterval(() => {
    peerConnection.getStats().then((stats) => {
      stats.forEach((report) => {
        if (report.type === 'inbound-rtp') {
          console.log('Inbound RTP:', {
            bytesReceived: report.bytesReceived,
            packetsLost: report.packetsLost
          });
        }
      });
    });
  }, 5000);
}

function handleConnectionFailure() {
  console.error('Connection failed, attempting restart');
  peerConnection.restartIce();
}

---

Takeaway

WebRTC failures stem from ICE issues, SDP negotiation problems, media access, or data channel misconfiguration. The key to reliability is:

1. Configure TURN servers for production
2. Handle errors gracefully at every step
3. Monitor connection states continuously
4. Test with real devices and network conditions
5. Log extensively for debugging

Implement these patterns, and your WebRTC connections will be significantly more robust.