RTCPeerConnectionIceErrorEvent.errorText — Eigenschaft · JavaScript-Referenz

Signatur

RTCPeerConnectionIceErrorEvent.errorText

Beschreibung

Die Eigenschaft errorText gehört zum Interface RTCPeerConnectionIceErrorEvent. Dieses Event wird beim Ereignis icecandidateerror einer RTCPeerConnection ausgelöst. Sie enthält einen lesbaren Text zum Fehler, der beim Sammeln der ICE-Kandidaten (ICE Gathering) über einen STUN- oder TURN-Server aufgetreten ist, z. B. "Unauthorized" bei falschen TURN-Zugangsdaten oder "Allocation Quota Reached".

Meist stammt der Text direkt aus der Reason Phrase der STUN-Fehlerantwort (siehe RFC 5389/8489). Antwortet der Server gar nicht, setzt der Browser errorCode auf 701. Den Text in errorText erzeugt dann der Browser selbst, z. B. "STUN host lookup received error." oder einen Hinweis auf eine Zeitüberschreitung.

Nutzen Sie errorText vor allem zur Diagnose und Protokollierung: zusammen mit errorCode, url, address und port lässt sich schnell eingrenzen, welcher ICE-Server falsch konfiguriert oder nicht erreichbar ist. Für die Programmlogik ist der numerische errorCode besser geeignet, denn der Text ist weder standardisiert noch zwischen Browsern stabil.

Rückgabewert

Typ

string

Beschreibung

Der Fehlertext des STUN-/TURN-Servers oder ein vom Browser erzeugter Beschreibungstext. Die Eigenschaft ist nur lesbar. Ist kein Text vorhanden, kann der Wert ein leerer String sein.

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}`
  );
});

// Kandidatensuche anstoßen
pc.createDataChannel('probe');
pc.createOffer().then((offer) => pc.setLocalDescription(offer));

ICE-Fehler 401 bei turn:turn.example.com:3478?transport=udp: Unauthorized

Fehler per on-Property nach Ursache einordnen

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

pc.onicecandidateerror = ({ errorCode, errorText, url }) => {
  if (errorCode === 701) {
    // Server nicht erreichbar – Text stammt vom Browser
    console.error(`Server nicht erreichbar (${url}): ${errorText}`);
  } else if (errorCode === 401) {
    console.error('TURN-Zugangsdaten ungültig:', errorText);
  } else {
    console.error(`STUN/TURN-Fehler ${errorCode}: ${errorText}`);
  }
};

pc.createDataChannel('probe');
await pc.setLocalDescription(await pc.createOffer());

Server nicht erreichbar (stun:nicht-vorhanden.example:3478): STUN host lookup received error.

ICE-Fehler für Telemetrie sammeln

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

const onIceError = (e) => {
  iceErrors.push({
    code: e.errorCode,
    text: e.errorText,
    url: e.url,
    address: e.address,
    port: e.port,
    time: Date.now()
  });
};
pc.addEventListener('icecandidateerror', onIceError);

pc.addEventListener('icegatheringstatechange', () => {
  if (pc.iceGatheringState === 'complete') {
    pc.removeEventListener('icecandidateerror', onIceError);
    console.log('Gesammelte ICE-Fehler:', iceErrors);
    // z. B. per navigator.sendBeacon('/telemetry', JSON.stringify(iceErrors));
  }
});

pc.createDataChannel('probe');
await pc.setLocalDescription(await pc.createOffer());

Gesammelte ICE-Fehler: [{ code: 401, text: 'Unauthorized', ... }]

// Wichtig · Fallstricke

Nicht für Programmlogik verwenden: Der Text ist nicht standardisiert. Er unterscheidet sich je nach Server und Browser und kann sich zwischen Versionen ändern. Werten Sie stattdessen errorCode aus (300–699 = STUN-Fehlercodes, 701 = Server nicht erreichbar).
Kein Grund zum Abbruch: Ein icecandidateerror-Event bedeutet nicht, dass die Verbindung scheitert. Andere Kandidaten oder Server können trotzdem funktionieren. Bewerten Sie den Verbindungszustand über iceConnectionState bzw. connectionState.
Datenschutz: Ereignisse mit errorText enthalten oft auch address/port und damit lokale IP-Adressen. Das Feld address kann aus Datenschutzgründen null sein oder eine verschleierte Adresse (mDNS) enthalten. Bereinigen Sie die Daten vor dem Senden an eine Telemetrie.
Kompatibilität: Chromium-basierte Browser unterstützen das Event seit Version 77, Safari seit 15.4. Firefox unterstützt es erst in neueren Versionen. Prüfen Sie bei Bedarf mit 'onicecandidateerror' in RTCPeerConnection.prototype, ob es verfügbar ist.
Ältere Chrome-Versionen hatten zusätzlich eine inzwischen entfernte Eigenschaft hostCandidate. Verwenden Sie stattdessen address und port.

Siehe auch

RTCPeerConnectionIceErrorEvent RTCPeerConnectionIceErrorEvent.errorCode RTCPeerConnectionIceErrorEvent.url RTCPeerConnectionIceErrorEvent.address RTCPeerConnection