new RTCPeerConnectionIceErrorEvent() — Methode · JavaScript-Referenz

Signatur

new RTCPeerConnectionIceErrorEvent(type, options)

Beschreibung

Der Konstruktor RTCPeerConnectionIceErrorEvent() erzeugt ein neues Ereignisobjekt vom Typ RTCPeerConnectionIceErrorEvent. Der Browser feuert solche Ereignisse normalerweise selbst als icecandidateerror auf einer RTCPeerConnection. Das passiert, wenn beim Sammeln von ICE-Kandidaten (ICE Gathering) ein STUN- oder TURN-Server einen Fehler meldet oder gar nicht erreichbar ist.

Selbst aufrufen muss man den Konstruktor nur selten. Nützlich ist er vor allem in Unit-Tests und Mocks, wenn Sie die Fehlerbehandlung Ihrer WebRTC-Anwendung prüfen wollen, ohne einen Server-Ausfall nachzustellen. Auch in Polyfills und Abstraktionsschichten, die eigene Ereignisse weiterreichen, kommt er zum Einsatz.

Die Werte aus dem options-Objekt landen in den schreibgeschützten Eigenschaften address, port, url, errorCode und errorText. errorCode ist laut Spezifikation Pflicht. Werte von 300 bis 699 sind STUN-Fehlercodes (z. B. 401 für „Unauthorized“), 701 steht für einen Netzwerkfehler, bei dem der Server nicht erreichbar war.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, normalerweise `"icecandidateerror"`.
$options Pflicht	RTCPeerConnectionIceErrorEventInit		Objekt zur Initialisierung. Es enthält die Felder aus `EventInit` (`bubbles`, `cancelable`, `composed`) und zusätzlich die folgenden.
$options.errorCode Pflicht	number		STUN-Fehlercode (300–699) oder `701`, wenn der Server nicht erreichbar war.
$options.errorText	string	""	Lesbare Fehlerbeschreibung, z. B. die STUN-Reason-Phrase.
$options.address	string \| null	null	Lokale IP-Adresse, über die mit dem Server kommuniziert wurde. Aus Datenschutzgründen oft verschleiert oder `null`.
$options.port	number \| null	null	Lokaler Port der Verbindung zum Server.
$options.url	string	""	URL des STUN- oder TURN-Servers, bei dem der Fehler aufgetreten ist, z. B. `"turn:turn.example.com:3478"`.

Rückgabewert

Typ

RTCPeerConnectionIceErrorEvent

Beschreibung

Ein neues Ereignisobjekt, dessen Eigenschaften mit den übergebenen Werten belegt sind.

Beispiele

Ereignis erzeugen und Eigenschaften lesen

const event = new RTCPeerConnectionIceErrorEvent('icecandidateerror', {
  address: '192.0.2.10',
  port: 54321,
  url: 'turn:turn.example.com:3478',
  errorCode: 401,
  errorText: 'Unauthorized'
});

console.log(event.type);
console.log(event.errorCode, event.errorText);
console.log(event.url);

icecandidateerror 401 Unauthorized turn:turn.example.com:3478

Fehlerbehandlung im Test mit einem simulierten Ereignis prüfen

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.example.com:3478' }]
});

const handleIceError = (e) => {
  if (e.errorCode === 701) {
    console.warn(`Server nicht erreichbar: ${e.url}`);
  } else {
    console.error(`STUN/TURN-Fehler ${e.errorCode}: ${e.errorText}`);
  }
};

pc.addEventListener('icecandidateerror', handleIceError);

// Ausfall simulieren, ohne dass ein echter Server wegbrechen muss
pc.dispatchEvent(new RTCPeerConnectionIceErrorEvent('icecandidateerror', {
  url: 'stun:stun.example.com:3478',
  errorCode: 701,
  errorText: 'STUN host lookup failed'
}));

pc.close();

Server nicht erreichbar: stun:stun.example.com:3478

Echte ICE-Fehler über die on-Eigenschaft protokollieren

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

pc.onicecandidateerror = ({ url, errorCode, errorText, address, port }) => {
  console.log({ url, errorCode, errorText, address, port });
};

// Startet das ICE Gathering
pc.createDataChannel('probe');
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

{ url: 'turn:turn.example.com:3478', errorCode: 401, errorText: 'Unauthorized', address: '192.0.2.x', port: 54321 }

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser und Safari unterstützen den Konstruktor. Firefox unterstützt ihn nur eingeschränkt oder gar nicht. Prüfen Sie vorher mit typeof RTCPeerConnectionIceErrorEvent === 'function'.
Kein Verbindungsabbruch: Ein icecandidateerror heißt nicht, dass die Verbindung scheitert. Andere Server oder Kandidaten können trotzdem funktionieren. Den Zustand der Verbindung zeigt iceConnectionState bzw. connectionState.
Veraltete Eigenschaft: Frühere Entwürfe enthielten hostCandidate. Diese Eigenschaft wurde durch address und port ersetzt und sollte nicht mehr verwendet werden.
Datenschutz: Die Werte von address können aus Datenschutzgründen verschleiert (mDNS) oder null sein. Speichern Sie diese Daten nicht ungefiltert in Logs.
Selbst erzeugte Ereignisse haben isTrusted === false. Sie lösen im Browser kein internes WebRTC-Verhalten aus, sondern nur Ihre eigenen Listener.

Siehe auch

RTCPeerConnectionIceErrorEvent RTCPeerConnection RTCPeerConnectionIceEvent EventTarget.dispatchEvent() new GPUPipelineError() new GPUUncapturedErrorEvent()