RTCErrorEvent.error — Eigenschaft · JavaScript-Referenz

Signatur

RTCErrorEvent.error

Beschreibung

Die Eigenschaft error eines RTCErrorEvent liefert ein RTCError-Objekt. Ein RTCErrorEvent wird als error-Ereignis ausgelöst, z. B. an einem RTCDataChannel (etwa bei SCTP-Abbruch oder Übertragungsfehlern) oder an einem RTCDtlsTransport (bei DTLS-Handshake- oder Fingerprint-Fehlern).

RTCError erbt von DOMException. Du bekommst also die üblichen Felder name und message und dazu WebRTC-spezifische Angaben:

errorDetail: Fehlerkategorie, z. B. "data-channel-failure", "dtls-failure", "fingerprint-failure", "sctp-failure", "sdp-syntax-error", "hardware-encoder-error" oder "hardware-encoder-not-available"
sctpCauseCode: SCTP-Fehlercode bei "sctp-failure", sonst null
receivedAlert / sentAlert: DTLS-Alert-Code bei "dtls-failure", sonst null
sdpLineNumber: Zeilennummer bei "sdp-syntax-error", sonst null

Du nutzt die Eigenschaft in Fehlerbehandlern, um Verbindungsprobleme genau zu erkennen, sie zu protokollieren und gezielt zu reagieren, etwa mit einem neuen Kanal, einer ICE-Neuverhandlung (ICE-Restart) oder einer Meldung an den Nutzer.

Rückgabewert

Typ

RTCError

Beschreibung

Ein RTCError-Objekt (Unterklasse von DOMException) mit name, message, errorDetail und den je nach Fehlerart gefüllten Feldern sctpCauseCode, receivedAlert, sentAlert und sdpLineNumber.

Beispiele

Fehler eines Datenkanals mit addEventListener auswerten

const pc = new RTCPeerConnection();
const channel = pc.createDataChannel('chat');

const onChannelError = (event) => {
  const err = event.error; // RTCError
  console.error(`Datenkanal-Fehler: ${err.errorDetail} – ${err.message}`);

  if (err.errorDetail === 'sctp-failure') {
    console.error('SCTP-Cause-Code:', err.sctpCauseCode);
  }
};

channel.addEventListener('error', onChannelError);

// Später, z. B. beim Aufräumen:
// channel.removeEventListener('error', onChannelError);

Datenkanal-Fehler: sctp-failure – User-Initiated Abort SCTP-Cause-Code: 12

DTLS-Fehler über die onerror-Eigenschaft behandeln

const pc = new RTCPeerConnection();
pc.createDataChannel('init');

pc.addEventListener('connectionstatechange', () => {
  const sender = pc.getSenders()[0];
  const dtls = pc.sctp?.transport ?? sender?.transport;
  if (!dtls || dtls.onerror) return;

  dtls.onerror = (event) => {
    const { errorDetail, receivedAlert, sentAlert } = event.error;
    console.warn('DTLS-Problem:', errorDetail, { receivedAlert, sentAlert });
  };
});

DTLS-Problem: dtls-failure { receivedAlert: 40, sentAlert: null }

RTCErrorEvent für Tests künstlich erzeugen

const channel = new RTCPeerConnection().createDataChannel('test');

channel.onerror = (event) => {
  console.log(event.error instanceof DOMException);
  console.log(event.error.errorDetail, event.error.message);
};

const error = new RTCError(
  { errorDetail: 'data-channel-failure' },
  'Simulierter Kanalabbruch'
);
channel.dispatchEvent(new RTCErrorEvent('error', { error }));

true data-channel-failure Simulierter Kanalabbruch

// Wichtig · Fallstricke

Schreibgeschützt: error wird nur über den Konstruktor new RTCErrorEvent(type, { error }) gesetzt. Beim Konstruktor ist error Pflicht.
Browser-Unterstützung: Chromium-Browser und Safari unterstützen RTCErrorEvent und RTCError. Firefox löst an RTCDataChannel teils nur ein generisches Event ohne error-Eigenschaft aus. Prüfe deshalb defensiv, etwa mit event.error?.errorDetail, und verlasse dich nicht auf ein bestimmtes Verhalten.
Die Felder sctpCauseCode, receivedAlert, sentAlert und sdpLineNumber sind nur bei passendem errorDetail gefüllt, sonst null.
Der Text in message ist je nach Browser unterschiedlich und nicht standardisiert. Für Programmlogik nimm errorDetail, nicht message.
Fehler aus Promise-basierten Aufrufen wie setRemoteDescription() kommen nicht als Ereignis. Sie werden als abgelehnte Promise gemeldet, wobei ein RTCError übergeben werden kann. Fange sie mit try/catch ab.

Siehe auch

ErrorEvent.error SensorErrorEvent.error RTCError.sentAlert ErrorEvent.colno RTCTrackEvent.track