Blog

WebRTC connection failed: how to find out why a video call doesn't connect

· Andrij Tkachenko · 4 min read

Two browser windows joined by a dotted line that breaks in the middle, with a magnifying glass over the gap

A WebRTC connection fails when the two devices have tried every path they know between them and none works. The cause is nearly always a network that blocks the path, a TURN server that is missing or broken, or candidates that never reached the other side, and you can tell which in a few minutes.

This post goes through how to find it: what "failed" really means, how to test the network on each side, how to check your TURN server, and what to look at in the browser.

What "failed" means

Before a call connects, each browser gathers its candidates, the addresses it might be reached at. Your signaling server passes them to the other side, and the browsers try pairs of them until one gets through. This is ICE, and when every pair has failed, the connection goes to failed.

Log the states on both sides first, as they show how far a call got:

JavaScript
pc.onconnectionstatechange = () => console.log('connection', pc.connectionState);
pc.oniceconnectionstatechange = () => console.log('ice', pc.iceConnectionState);
pc.onicegatheringstatechange = () => console.log('gathering', pc.iceGatheringState);

Firefox says it more plainly in its console: "ICE failed, add a TURN server". That is good advice, though not always the whole story.

Step 1: test the network on each side

Open the WebRTC test on both devices. It needs no account and no permission, so you can send it to the person whose call fails. It checks the browser, whether UDP gets out, how the network maps addresses, and whether a relay and a WebSocket get through. Then it says in plain words what it found:

  • WebRTC doesn't work in this browser. An extension, a VPN or a company policy has often switched it off. Nothing about the network matters until that is fixed.
  • UDP looks blocked. Direct calls can't connect from here. Only a relay over TCP can carry a call, usually on port 443.
  • Calls will often need a relay. The network is a symmetric NAT, which gives each server it talks to a different port. The port another device learns then doesn't work for it, so direct connections often fail.
  • Calls should connect. The network keeps a steady address and lets UDP out. If this side is fine, look at the other one.

Two people can each pass and still fail together, as a direct path needs both networks to allow it. That is what a relay is for.

Step 2: check your TURN server

If either side needs a relay and the call still fails, the TURN server is the next suspect. The usual problems:

  • There isn't one. With only STUN in iceServers, a call between two strict networks has no path at all. It works in your office and fails for some of your users.
  • Its credentials have expired. Time-limited credentials made when the page loaded can run out before a call starts.
  • Its relay ports are closed. The server hands out an address, and no data passes.
  • It offers one way in only. A network that blocks UDP needs TURN over TCP or TLS, ideally on port 443.

How to test a TURN server goes through each of these, with our TURN server test to run them. STUN and TURN servers explains what each one is for.

Step 3: look at the candidates

If the network and the relay look fine, see what the browsers actually tried. Open chrome://webrtc-internals in Chrome or Edge, or about:webrtc in Firefox, in another tab while the call runs. Both list each connection, its candidates and which pairs were tried.

What you find points to the cause:

  • Only host candidates. The browser never reached a STUN server, so it has only local addresses, which are no use from another network. Check the iceServers you passed and that the server can be reached.
  • No relay candidate. The TURN server refused the login or didn't answer. The candidate errors say which.
  • Candidates here but none from the other side. They never arrived, which points to your signaling. Check that each side sends them and adds them.
  • Candidates on both sides, and every pair failed. The networks are blocking the path, and without a relay that has no fix on your side.

A common cause of missing candidates is timing: adding one before the remote description is set throws an error, and code that swallows the error loses the candidate. Queue them until setRemoteDescription() has finished.

If it connects and then drops

disconnected isn't failed. It means packets stopped for a moment, as they do when someone walks out of Wi-Fi range, and it often recovers by itself. Once it reaches failed, a call can recover without hanging up by trying again:

JavaScript
pc.onconnectionstatechange = () => {
  if (pc.connectionState === 'failed') {
    pc.restartIce();
  }
};

restartIce() makes the next offer gather and try again, so your signaling has to carry that new offer to the other side.

How WordPlus Cloud handles it

On WordPlus Cloud a call goes straight between two devices when it can, through the relay nearest each person when a firewall blocks that, and through our media servers when even the relays cannot reach, without hanging up. So there is a next path to fall back on, and none of it for you to run. How we connect your users shows where those servers are, and connecting users across regions explains how calls span them.

If a call on our network fails, the connection test shows whether that network reaches our servers. The docs on calls and video calls for apps show how to build on it.