RTCPeerConnectionIceErrorEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCPeerConnectionIceErrorEvent extends Event

Beschreibung

RTCPeerConnectionIceErrorEvent ist das Ereignisobjekt, das eine RTCPeerConnection beim Ereignis icecandidateerror übergibt. Das Ereignis tritt auf, wenn beim Sammeln von ICE-Kandidaten die Kommunikation mit einem STUN- oder TURN-Server scheitert. Gründe sind z. B. falsche Zugangsdaten, ein nicht erreichbarer Server oder eine Zeitüberschreitung.

Die Schnittstelle erbt von Event und hat zusätzlich diese schreibgeschützten Eigenschaften:

address: lokale IP-Adresse, über die mit dem Server gesprochen wurde, oder null. Aus Datenschutzgründen ist sie oft verschleiert, etwa als mDNS-Name.
port: lokaler Port oder null.
url: URL des STUN- oder TURN-Servers, bei dem der Fehler auftrat.
errorCode: numerischer Fehlercode. Werte von 300 bis 699 kommen direkt vom STUN-Server (z. B. 401 Unauthorized, 437 Allocation Mismatch). Werte von 700 bis 799 setzt der Browser, wenn der Server nicht erreichbar war (701).
errorText: Fehlertext vom Server oder eine Beschreibung des Browsers.

Das Ereignis ist vor allem bei der Diagnose nützlich, etwa um falsch eingerichtete TURN-Server oder abgelaufene Zugangsdaten zu erkennen. Ein einzelnes icecandidateerror bedeutet nicht, dass die Verbindung scheitert: Andere Kandidaten (z. B. Host-Kandidaten oder weitere Server) können trotzdem funktionieren. Ob die Verbindung wirklich fehlgeschlagen ist, zeigt iceConnectionState bzw. connectionState.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, normalerweise `"icecandidateerror"` (Konstruktor `new RTCPeerConnectionIceErrorEvent(type, options)`).
$options Pflicht	object		Wörterbuch mit `errorCode` (number, Pflicht) sowie optional `address`, `port`, `url`, `errorText` und den üblichen `Event`-Optionen wie `bubbles` und `cancelable`.

Rückgabewert

Typ

RTCPeerConnectionIceErrorEvent

Beschreibung

Beim Konstruktor-Aufruf ein neues Ereignisobjekt. Im Normalfall erzeugt der Browser das Objekt selbst und übergibt es dem Handler.

Beispiele

ICE-Fehler mit addEventListener protokollieren

const pc = new RTCPeerConnection({
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },
    { urls: 'turn:turn.example.com:3478', username: 'user', credential: 'falsch' }
  ]
});

pc.addEventListener('icecandidateerror', (event) => {
  console.warn(
    `ICE-Fehler ${event.errorCode} bei ${event.url}: ${event.errorText}`,
    `(lokal: ${event.address ?? '?'}:${event.port ?? '?'})`
  );
});

// Kandidatensuche auslösen
pc.createDataChannel('test');
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

ICE-Fehler 401 bei turn:turn.example.com:3478?transport=udp: Unauthorized (lokal: 1a2b3c.local:54321)

Fehlercodes auswerten mit der on-Property

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'turn:turn.example.com:3478', username: 'u', credential: 'p' }]
});

const describe = (code) => {
  if (code === 401) return 'Zugangsdaten ungültig oder abgelaufen';
  if (code === 701) return 'Server nicht erreichbar (Timeout/DNS/Firewall)';
  if (code >= 300 && code < 700) return 'STUN/TURN-Serverfehler';
  return 'Unbekannter Fehler';
};

pc.onicecandidateerror = (event) => {
  console.log(describe(event.errorCode), '→', event.url);
};

// Handler später wieder entfernen
// pc.onicecandidateerror = null;

Server nicht erreichbar (Timeout/DNS/Firewall) → turn:turn.example.com:3478?transport=udp

Ereignis manuell erzeugen (z. B. für Tests)

const event = new RTCPeerConnectionIceErrorEvent('icecandidateerror', {
  errorCode: 701,
  errorText: 'TURN host lookup received error.',
  url: 'turn:turn.example.com:3478',
  address: null,
  port: null
});

const pc = new RTCPeerConnection();
pc.addEventListener('icecandidateerror', (e) => console.log(e.errorCode, e.errorText));
pc.dispatchEvent(event);

701 TURN host lookup received error.

// Wichtig · Fallstricke

Kein Verbindungsabbruch: Das Ereignis kommt oft vor, z. B. wenn IPv6 nicht erreichbar ist oder ein einzelner Server nicht antwortet. Bau keine harte Fehlerbehandlung darauf auf. Prüfe stattdessen connectionState === 'failed'.
Veraltete Eigenschaft: hostCandidate ist veraltet und wurde durch address und port ersetzt. Ältere Chrome-Versionen kennen nur hostCandidate.
Datenschutz: address ist häufig null oder ein mDNS-Name (*.local), damit keine lokalen IP-Adressen nach außen gelangen.
Browserunterstützung: Firefox unterstützt das Ereignis erst seit Version 110, Safari seit 16.4. Prüfe die Unterstützung vorher mit 'onicecandidateerror' in RTCPeerConnection.prototype.
Ein errorCode von 701 kommt vom Browser selbst, nicht vom Server. Dann ist errorText browserabhängig und nicht einheitlich.

Siehe auch

RTCPeerConnection RTCPeerConnectionIceEvent RTCIceCandidate RTCPeerConnection.iceConnectionState Event