RTCPeerConnection: icecandidateerror event
==========================================

The WebRTC API event **`icecandidateerror`** is sent to an `RTCPeerConnection` if an error occurs while performing ICE negotiations through a STUN or TURN server. The event object is of type `RTCPeerConnectionIceErrorEvent`, and contains information describing the error in some amount of detail.

This event is not cancelable and does not bubble.

Syntax
------

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


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

onicecandidateerror = (event) => {};
```

Event type
----------

An `RTCPeerConnectionIceErrorEvent`. Inherits from `Event`.

Event

RTCPeerConnectionIceErrorEventEvent properties
----------------

*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.

Description
-----------

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`.

Example
-------

The following example establishes a handler for `icecandidateerror`s 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.


```js
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.

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-onicecandidateerror |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.