Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท Quality and Debugging

Debugging WebRTC: States, Errors and a Checklist

A practical WebRTC debugging guide: track connection and ICE states, read common error names, use chrome://webrtc-internals, and follow a checklist when a call will not connect.

WebRTC failures are famously quiet. A call "just does not connect", or there is video but no audio, or it works at home and fails at the office. There is no single error message to search for, because the problem might be in your signalling, your STUN/TURN setup, the user's firewall, or the SDP itself. The way out is a method: observe the state machines, log everything, and narrow down the layer that breaks.

This lesson gives you that method: the states to watch, the errors you will see, the tools the browsers provide, and a checklist for the most common failure, "ICE never connects".

The four state machines

A single RTCPeerConnection has several states. Learn them, because every bug shows up in one.

Property Event Values (simplified)
signalingState signalingstatechange stable, have-local-offer, have-remote-offer, have-local-pranswer, have-remote-pranswer, closed
iceGatheringState icegatheringstatechange new, gathering, complete
iceConnectionState iceconnectionstatechange new, checking, connected, completed, disconnected, failed, closed
connectionState connectionstatechange new, connecting, connected, disconnected, failed, closed
  • signalingState tells you where you are in the offer/answer dance. A stuck have-local-offer means the answer never arrived.
  • iceGatheringState shows whether candidates are being collected. If it jumps to complete with no relay candidate, your TURN configuration is wrong.
  • iceConnectionState reports the connectivity checks. failed means no candidate pair worked.
  • connectionState combines ICE and DTLS: the best single indicator for the UI.
stateDiagram-v2
  [*] --> new
  new --> connecting: checks start
  connecting --> connected: a pair works and DTLS completes
  connected --> disconnected: packets stop
  disconnected --> connected: recovers
  disconnected --> failed: gives up
  connecting --> failed: no pair works
  failed --> [*]
  connected --> closed: close()

connectionState: disconnected can recover by itself, failed cannot without an ICE restart.

Always attach loggers first

Make a tiny helper that logs every state change with a timestamp offset. Install it on every connection while you develop; it costs nothing and answers most "what happened" questions.

JS A state logger for every connection

Press Run (or Ctrl + Enter) to see the console output here.

No output.

You will see the signalling states first, then gathering, then ICE and connection states. The order of lines tells you which layer progressed and which stalled.

Errors you will meet

Most errors are DOMExceptions with a name. These are the frequent ones:

Name Typical cause
InvalidStateError A call at the wrong time: answer in stable, addIceCandidate before a remote description, send on a non-open channel
OperationError The SDP was invalid or incompatible (bad syntax, mismatched m-lines, DTLS role problem)
InvalidAccessError Bad iceServers, for example a turn: URL without credentials
SyntaxError Malformed URL in iceServers
NotAllowedError The user or policy denied camera or microphone access
NotFoundError No device matches the constraints
OverconstrainedError Constraints cannot be satisfied (exact resolution not available)
TypeError Wrong argument, such as both maxRetransmits and maxPacketLifeTime
JS Provoke the common errors on purpose

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Read the name first, then the message. If the name is InvalidStateError, print pc.signalingState right before the failing call; the answer is almost always there.

Browser tools

  • chrome://webrtc-internals (Chrome, Edge): lists every peer connection on every tab, the full SDP offers and answers, every API call and state change, and live graphs of the stats from Reading getStats. You can download a dump to share with a colleague.
  • about:webrtc (Firefox): states, candidates, SDP, and ICE statistics, with a connection log.
  • Safari: the Web Inspector console plus the getStats() data; enable "WebRTC logging" in the Develop menu.
  • Wireshark: filters like stun, dtls and rtp show what really crosses the network. Everything past the DTLS handshake is encrypted, but you can still see whether packets flow.

Checklist: ICE never connects

Work from the top; each step rules out a layer.

  1. Did both peers receive the offer and answer? Log signalingState on both. If one side is stuck at have-local-offer, the signalling message was lost.
  2. Did candidates reach the other peer? Log every onicecandidate you send and every addIceCandidate you call. A common bug is dropping candidates that arrive before the remote description (queue them until it is set).
  3. Any srflx candidate? If not, STUN is unreachable (blocked UDP, wrong URL).
  4. Any relay candidate? If not, TURN credentials, URL or ports are wrong. Test with iceTransportPolicy: 'relay' to isolate it.
  5. Is the TURN secret expired? Time-limited credentials with a wrong server clock fail in confusing ways.
  6. Does candidate-pair show any succeeded pair? If all pairs are failed or waiting, the network blocks them.
  7. Is a firewall blocking UDP? Offer turns: on port 443 over TCP.
  8. Is the page secure? Camera and microphone need HTTPS or localhost.
  9. Is there a certificate or DTLS problem? transport.dtlsState: 'failed' with working ICE points to it.
JS Stand-in: a failure triage helper

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Habits that make debugging easier

  • Give every connection a name or id in logs, especially in group calls.
  • Log both ends and compare, since the bug is often in the message you assumed arrived.
  • Reproduce with iceTransportPolicy: 'relay' and again with the default, to separate TURN problems from NAT problems.
  • Save webrtc-internals dumps from failing sessions; support teams love them.
  • Do not log secrets (TURN credentials, tokens) to analytics.

Common mistakes

  • Treating disconnected as final. It can recover; wait a few seconds before restarting ICE.
  • Ignoring failed. It will not recover on its own; call pc.restartIce() and renegotiate (see WebRTC in Real Apps).
  • Only testing on localhost. NAT, firewalls and mobile networks create different failures.
  • Swallowing promise rejections. Always catch and log err.name.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which state property is the best single indicator for the connection status in your UI?

    connectionState combines ICE and DTLS into one value: new, connecting, connected, disconnected, failed, closed.
  2. 2. addIceCandidate() on a connection with no remote description throws which error?

    A candidate needs a remote description to attach to; calling too early is a wrong-state error.
  3. 3. Your gathered candidates include only host types. What is the most likely cause?

    srflx comes from STUN and relay from TURN; without them only local host addresses exist.
  4. 4. Where can you inspect SDP and live stats for all peer connections in Chrome?

    webrtc-internals shows every connection, its SDP, API calls and stats graphs.

Summary

  • Watch four state machines: signalling, ICE gathering, ICE connection and connection state.
  • Log every state change and every candidate on both peers.
  • Error names tell you the layer: InvalidStateError, OperationError, InvalidAccessError, NotAllowedError.
  • Use chrome://webrtc-internals or about:webrtc, and test with relay-only policy.
  • Follow the checklist from signalling to candidates, STUN, TURN, firewalls and DTLS.

Next: Security: DTLS, SRTP and Fingerprints