RTCError.errorDetail — Eigenschaft · JavaScript-Referenz

Signatur

get RTCError.prototype.errorDetail

Beschreibung

Die Eigenschaft errorDetail eines RTCError-Objekts gibt an, welcher WebRTC-Fehler genau aufgetreten ist. RTCError erbt von DOMException. Sein name ist fast immer "OperationError" und sagt deshalb wenig aus. Erst errorDetail zeigt, ob etwa der DTLS-Handshake, die SCTP-Übertragung oder das Parsen der SDP fehlgeschlagen ist.

Der Wert gehört zur Aufzählung RTCErrorDetailType. Mögliche Werte sind:

"data-channel-failure": Der Datenkanal ist ausgefallen.
"dtls-failure": Die DTLS-Aushandlung ist fehlgeschlagen oder die Verbindung wurde mit einem schwerwiegenden Fehler beendet. Mehr dazu steht in receivedAlert und sentAlert.
"fingerprint-failure": Das Zertifikat der Gegenstelle passt zu keinem Fingerabdruck in der SDP.
"sctp-failure": Die SCTP-Aushandlung ist fehlgeschlagen. Den Grund liefert sctpCauseCode.
"sdp-syntax-error": Die SDP enthält einen Syntaxfehler. Die betroffene Zeile steht in sdpLineNumber.
"hardware-encoder-not-available" und "hardware-encoder-error": Der Hardware-Encoder fehlt oder hat die übergebenen Parameter nicht verarbeiten können.

Typischerweise liest man errorDetail im error-Ereignis eines RTCDataChannel. Dort liegt das Fehlerobjekt in event.error (ein RTCErrorEvent). Ein zweiter Einsatzort ist der catch-Zweig von Promise-basierten Methoden wie setRemoteDescription(). Anhand des Werts kann die Anwendung gezielt reagieren: neu verbinden, eine Fehlermeldung anzeigen oder protokollieren.

Rückgabewert

Typ

string

Beschreibung

Einer der Werte aus RTCErrorDetailType, z. B. "dtls-failure", "sctp-failure" oder "sdp-syntax-error".

Beispiele

Fehler eines Datenkanals auswerten

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

// Variante 1: addEventListener
channel.addEventListener('error', (event) => {
  const err = event.error; // RTCError
  switch (err.errorDetail) {
    case 'sctp-failure':
      console.warn('SCTP-Fehler, Cause Code:', err.sctpCauseCode);
      break;
    case 'dtls-failure':
      console.warn('DTLS-Fehler, empfangener Alert:', err.receivedAlert);
      break;
    case 'data-channel-failure':
      console.warn('Datenkanal ausgefallen:', err.message);
      break;
    default:
      console.error('Unbekannter WebRTC-Fehler:', err.errorDetail);
  }
});

// Variante 2: on-Property
channel.onerror = (event) => console.log(event.error.errorDetail);

SCTP-Fehler, Cause Code: 12

RTCError selbst erzeugen (z. B. für Tests)

const err = new RTCError(
  { errorDetail: 'sdp-syntax-error', sdpLineNumber: 7 },
  'Ungültige a=rtpmap-Zeile'
);

console.log(err.name);          // von DOMException geerbt
console.log(err.errorDetail);
console.log(err.sdpLineNumber);
console.log(err instanceof DOMException);

OperationError sdp-syntax-error 7 true

Fehler aus einer Promise-basierten Methode behandeln

const applyRemoteOffer = async (pc, sdp) => {
  try {
    await pc.setRemoteDescription({ type: 'offer', sdp });
  } catch (err) {
    // Nicht jeder Fehler ist ein RTCError – vorher prüfen
    if (typeof RTCError !== 'undefined' && err instanceof RTCError) {
      if (err.errorDetail === 'sdp-syntax-error') {
        console.error(`SDP-Fehler in Zeile ${err.sdpLineNumber}`);
      }
    } else {
      console.error(`${err.name}: ${err.message}`);
    }
  }
};

applyRemoteOffer(new RTCPeerConnection(), 'kaputte SDP');

InvalidAccessError: Failed to execute 'setRemoteDescription' ... (browserabhängig)

// Wichtig · Fallstricke

Browser-Unterstützung: RTCError und errorDetail gibt es in Chromium-basierten Browsern und in Safari. Firefox unterstützt die Schnittstelle nicht. Prüfe deshalb vor der Verwendung mit typeof RTCError !== 'undefined'. Ohne diese Schnittstelle bleiben nur err.name und err.message.
Nicht jeder WebRTC-Fehler ist ein RTCError: Viele Methoden werfen weiterhin eine einfache DOMException, etwa InvalidStateError oder InvalidAccessError. Bei diesen ist errorDetail nicht vorhanden (undefined). Prüfe mit instanceof RTCError, bevor du auf die Eigenschaft zugreifst.
Nur lesbar: Eine Zuweisung an errorDetail wird stillschweigend ignoriert, im Strict Mode löst sie einen TypeError aus. Den Wert legt man ausschließlich über den Konstruktor new RTCError(init, message) fest.
Zusatzfelder hängen vom Wert ab: sdpLineNumber, sctpCauseCode, receivedAlert und sentAlert sind nur bei der passenden Fehlerart gesetzt, sonst null.
Browser können in künftigen Versionen neue Werte ergänzen. Sieh im switch daher immer einen default-Zweig vor.

Siehe auch

RTCError.sentAlert RTCError.receivedAlert RTCError.sctpCauseCode RTCError.sdpLineNumber RTCErrorEvent.error