Why WebRTC Connections Fail, and How to Fix Them

RTCPeerConnection.iceConnectionState moves through seven values defined by the W3C WebRTC specification. Where a connection stops tells you which part of the system to look at.

Two related states are easy to confuse. connectionState aggregates ICE and DTLS, so a connection can show ICE connected and overall failed when the DTLS handshake fails, typically because the certificate fingerprint in the SDP does not match. And disconnected comes from consent freshness checks (RFC 7675): treating it as fatal the instant it appears tears down connections that would have recovered.

No TURN server configured

STUN tells a browser its public address so the two sides can attempt UDP hole punching. That works on many home networks, but not everywhere, and an application configured with STUN only has no path left when hole punching fails. TURN (RFC 8656) relays the traffic instead. A WebRTC deployment without TURN will fail for some share of users, and nothing in the browser can work around it. STUN vs TURN explains the candidate types.

UDP blocked

Guest, hotel, school and corporate networks often allow only outbound TCP to ports 80 and 443. STUN then returns nothing, no server-reflexive candidates appear, and only a TURN server on TCP or TLS can carry the connection. When an HTTP proxy is mandatory as well, only traffic that can pass through it works; a TLS-inspecting proxy can break even TURN over TLS. The corporate firewalls and proxies guide covers those networks.

Address-dependent NAT on both sides

Hole punching relies on a NAT reusing the same public mapping for a local socket whatever the destination (“endpoint-independent mapping” in RFC 4787 terms). NATs that create a new mapping per destination, often called symmetric NATs, give the STUN server one port and the peer another. One such NAT can sometimes still connect through peer-reflexive candidates; two of them, one on each side, generally cannot. Carrier-grade NAT on mobile networks adds another layer. The NAT traversal guide goes through the behaviours.

mDNS host candidates

To avoid exposing local IP addresses to every web page, browsers replace private host addresses in candidates with random names ending in .local, which the other peer must resolve with multicast DNS. That resolution fails when the two devices are on different VLANs or subnets, when the Wi-Fi blocks multicast (client isolation is common on guest networks), or when security software filters it. The two devices then cannot use the LAN path and depend on server-reflexive candidates (which need the router to support hairpinning) or on TURN. Granting camera or microphone permission makes Chrome expose real local addresses, which is why the Trickle ICE sample has a button for it.

Browser privacy settings and extensions

RFC 8828 defines how much address information a browser may expose, from all interfaces down to traffic forced through a proxy. Chrome extensions can choose among these with the webRTCIPHandlingPolicy setting (default, default_public_and_private_interfaces, default_public_interface_only, disable_non_proxied_udp), and some privacy extensions set the strictest one, which disables direct UDP entirely. In Firefox, setting media.peerconnection.enabled to false in about:config turns WebRTC off. If one user always fails, check their extensions first.

VPN and firewall software

Desktop firewalls may block UDP for the browser process, and VPN clients may block traffic outside the tunnel or restrict candidates to the tunnel interface. The VPN server's own NAT then decides whether a direct path is possible.

TURN misconfiguration and expired credentials

TURN servers normally use short-lived credentials generated by the application server. A page that caches them past their lifetime gets 401 errors and no relay candidates. Other common mistakes: turn: where turns: was meant, a missing ?transport=tcp, the wrong port, or a turns: hostname that does not match the server's certificate. Failures surface as icecandidateerror events: a STUN error code such as 401 from the server, or 701 when the server could not be reached at all.

Signaling bugs

With trickle ICE (RFC 8838) candidates are sent as they are found, so ordering matters. Classic bugs: calling addIceCandidate() before setRemoteDescription() (it throws unless candidates are queued), dropping candidate messages on a reconnecting signaling socket, sending candidates to the wrong peer in a multi-party room, and both sides creating offers at once (glare). These show up as a connection stuck in new or checking with an empty or short remote candidate list.

1. Capture the failure. Open chrome://webrtc-internals (Chrome, Edge) in a separate tab before connecting; Firefox users open about:webrtc. Reproduce the failure, then find the peer connection.
2. Check signaling. In the event log, confirm that setRemoteDescription succeeded and that addIceCandidate calls arrived. No remote candidates means the problem is in your signaling, not the network.
3. Check local candidates. Look for srflx (STUN reached, UDP works) and relay (TURN allocation succeeded). Missing srflx suggests UDP is blocked; missing relay means TURN is absent, unreachable or rejecting the credentials.
4. Check the pairs. The candidate-pair stats show each pair's state (waiting, in-progress, failed, succeeded). If both sides have srflx candidates and every pair failed, the NATs do not allow hole punching and only TURN will work. If the only host candidates are .local names and the devices share a network, suspect mDNS.
5. Test your ICE servers in isolation with the Trickle ICE sample page: enter the STUN or TURN URL and credentials and click “Gather candidates”. A srflx row proves STUN works; a relay row proves TURN works. Setting IceTransports to relay tests TURN alone, and errors from icecandidateerror are listed above the table.
6. Repeat on the other side. Two endpoints mean two networks; the blocking one is often only one of them.

Checking the network from the command line

The SRIFT CLI includes a network check that runs its probes in parallel and reports each as working, warning, blocked or skipped, with a fix for anything that is not working:

srift doctor          # DNS, HTTPS, WebSocket, UDP STUN, proxy, daemon and sandbox checks
srift doctor --deep   # also creates an encrypted single-use 2 MB link and downloads it back
srift doctor --json   # machine-readable result

Among other things, it resolves DNS, fetches /compat.json over HTTPS (detecting captive portals and clock skew over five minutes), opens a WebSocket, sends a UDP STUN request to stun.cloudflare.com:3478, and checks proxy settings, the local daemon and whether it can start background processes. The verdict is ok, degraded or blocked, with the plan the CLI will use to serve files.

SRIFT treats a direct WebRTC connection as an optimisation, not a requirement. In a browser session:

• WebRTC is attempted only when it can work. A short probe checks whether a STUN server returns a server-reflexive candidate, and the browser fetches short-lived TURN credentials (TURN over TLS on port 443 is listed first). If neither UDP nor TURN is available, the transfer goes straight to the relay.
• A 3-second head start. If the direct data channel is not open within 3 seconds, the transfer runs over the WebSocket relay, with each chunk sealed with AES-256-GCM so the relay forwards ciphertext.
• A 6-second grace period on “disconnected”. The direct path is abandoned only if it has not recovered after 6 seconds; failed or closed end it at once.
• Mid-transfer failure is not a restart. The relay continues from the bytes the receiver already has.
• Signaling survives blocked WebSockets. If WebSockets cannot open, the session connection switches to an HTTPS long-polling stream.

So in SRIFT a WebRTC failure usually means a relayed transfer rather than a failed one; see why P2P transfers are slow for what that does to speed. Command-line quick-share links do not use WebRTC at all: they need only outbound HTTPS on port 443.

• Deploy TURN on UDP, TCP and TLS, with a turns: URL on port 443 for networks that allow nothing else.
• Mint TURN credentials per connection with a lifetime longer than the longest expected session, and never ship static credentials in a client bundle.
• Queue remote candidates until the remote description is set, and make signaling delivery reliable across reconnects.
• Treat disconnected as a warning. Wait a few seconds, then call restartIce(), which needs a new offer and answer through signaling.
• Record getStats() on failure: candidate types gathered, pair states and icecandidateerror codes. Without them, user reports are unanswerable.
• Have a fallback that is not WebRTC. A relay over HTTPS or WebSockets works on networks where even TURN is blocked by a proxy.