RTCPeerConnection: icecandidateerror event

Use the event name in methods like addEventListener(), or set an event handler property.

addEventListener("icecandidateerror", (event) => {});

onicecandidateerror = (event) => {};

An RTCPeerConnectionIceErrorEvent. Inherits from Event.

The RTCPeerConnectionIceErrorEvent interface includes the properties found on the Event interface, as well as the following properties:

address Read only

A string providing the local IP address used to communicate with the STUN or TURN server being used to negotiate the connection, or null if the local IP address has not yet been exposed as part of a local ICE candidate.

errorCode Read only

An unsigned integer value stating the numeric STUN error code returned by the STUN or TURN server. If no host candidate can reach the server, this property is set to the number 701, which is outside the range of valid STUN error codes. The 701 error is fired only once per server URL, and only while the icegatheringstate is gathering.

errorText Read only

A string containing the STUN reason text returned by the STUN or TURN server. If communication with the STUN or TURN server couldn't be established at all, this string will be a browser-specific string explaining the error.

port Read only

An unsigned integer value giving the port number over which communication with the STUN or TURN server is taking place, using the IP address given in address. null if the connection hasn't been established (that is, if address is null).

url Read only

A string indicating the URL of the STUN or TURN server with which the error occurred.

The error object's errorCode property is one of the numeric STUN error codes. There is one additional, WebRTC-specific, error which lies outside the valid STUN error code range: 701. Error 701 indicates that none of the ICE candidates were able to successfully make contact with the STUN or TURN server.

The 701 error is fired only once per server URL from the list of available STUN or TURN servers provided when creating the RTCPeerConnection. These errors occur only when the connection's ICE gathering state is gathering.

The following example establishes a handler for icecandidateerrors that occur on the RTCPeerConnection pc. This handler looks specifically for 701 errors that indicate that candidates couldn't reach the STUN or TURN server.

When this happens, the server URL and the error message are passed to a function called reportConnectFail() to log or output the connection failure.

pc.addEventListener("icecandidateerror", (event) => {
  if (event.errorCode === 701) {
    reportConnectFail(event.url, event.errorText);
  }
});

Note that if multiple STUN and/or TURN servers are provided when creating the connection, this error may happen more than once, if more than one of those servers fails. Each provided server is tried until a connection is established.