RTCDataChannel: error — Ereignis · JavaScript-Referenz

Signatur

dataChannel.addEventListener("error", handler) / dataChannel.onerror = handler

Beschreibung

Das error-Ereignis wird an einem RTCDataChannel ausgelöst, wenn im Datenkanal ein Fehler auftritt. Das kann zum Beispiel passieren, wenn die zugrunde liegende SCTP-Verbindung abbricht, eine Nachricht nicht übertragen werden kann oder die Gegenseite den Kanal fehlerhaft schließt. Das Ereignis ist nicht abbrechbar und steigt nicht im DOM auf.

Den Handler registriert man entweder mit addEventListener("error", handler) oder über die Eigenschaft onerror. Das Ereignisobjekt ist ein RTCErrorEvent. Dessen Eigenschaft error enthält ein RTCError-Objekt (abgeleitet von DOMException) mit genaueren Angaben:

errorDetail: Art des Fehlers, bei Datenkanälen meist "data-channel-failure" oder "sctp-failure".
sctpCauseCode: SCTP-Ursachencode nach RFC 4960, wenn errorDetail den Wert "sctp-failure" hat. Sonst ist er null.
receivedAlert / sentAlert: DTLS-Alert-Codes bei "dtls-failure".
message: eine lesbare Fehlermeldung.

In der Praxis nutzt man das Ereignis, um Fehler zu protokollieren, die Oberfläche zu informieren (z. B. „Verbindung unterbrochen“) und die Verbindung neu aufzubauen. Nach einem Fehler wird der Kanal meist geschlossen. Deshalb sollte man zusätzlich auf das close-Ereignis reagieren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"error"`, wenn man `addEventListener` verwendet.
$handler Pflicht	(event: RTCErrorEvent) => void		Callback, der das `RTCErrorEvent` erhält. Die Fehlerdetails stehen in `event.error`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (für das Abmelden per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein RTCErrorEvent, dessen Eigenschaft error ein RTCError enthält.

Beispiele

Fehler mit addEventListener auswerten

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

channel.addEventListener("error", (event) => {
  const err = event.error; // RTCError
  console.error("Datenkanal-Fehler:", err?.message);
  console.log("Detail:", err?.errorDetail);

  if (err?.errorDetail === "sctp-failure") {
    console.log("SCTP-Ursachencode:", err.sctpCauseCode);
  }
});

Datenkanal-Fehler: Transport channel closed Detail: sctp-failure SCTP-Ursachencode: 12

onerror-Eigenschaft mit UI-Hinweis

const pc = new RTCPeerConnection();
const channel = pc.createDataChannel("dateien", { ordered: true });
const status = document.querySelector("#status");

channel.onerror = (event) => {
  const detail = event.error?.errorDetail ?? "unbekannt";
  status.textContent = `Übertragung fehlgeschlagen (${detail})`;
};

channel.onclose = () => {
  status.textContent += " – Kanal geschlossen.";
};

Listener per AbortController wieder entfernen

const pc = new RTCPeerConnection();
const channel = pc.createDataChannel("telemetrie");
const controller = new AbortController();

const onError = (event) => {
  console.warn("Fehler im Kanal", channel.label, event.error?.message);
};

channel.addEventListener("error", onError, { signal: controller.signal });

// Später, z. B. beim Verlassen der Ansicht:
const cleanup = () => {
  controller.abort(); // entfernt den Listener
  // Alternativ: channel.removeEventListener("error", onError);
  channel.close();
  pc.close();
};

cleanup();
console.log("Aufgeräumt, Zustand:", channel.readyState);

Aufgeräumt, Zustand: closing

Automatischer Neuaufbau nach Fehler

const createChannel = (pc, label, attempt = 1) => {
  const channel = pc.createDataChannel(label);

  channel.addEventListener("error", (event) => {
    console.error(`Versuch ${attempt}:`, event.error?.errorDetail);
  });

  channel.addEventListener("close", () => {
    if (attempt < 3 && pc.connectionState === "connected") {
      setTimeout(() => createChannel(pc, label, attempt + 1), 1000 * attempt);
    }
  }, { once: true });

  return channel;
};

const pc = new RTCPeerConnection();
const channel = createChannel(pc, "sync");

// Wichtig · Fallstricke

Browser-Kompatibilität: Das error-Ereignis wird von allen modernen Browsern unterstützt. RTCErrorEvent und RTCError mit Feldern wie errorDetail und sctpCauseCode gibt es aber nicht in allen Browsern bzw. älteren Versionen (vor allem ältere Firefox-Versionen). Greifen Sie deshalb defensiv zu, z. B. mit event.error?.errorDetail.
Fehler bei send(): Ruft man send() auf einem Kanal auf, der noch nicht offen ist (readyState !== "open"), löst das kein error-Ereignis aus. Stattdessen wird synchron eine InvalidStateError-DOMException geworfen. Diese muss man mit try/catch abfangen.
Kanal ist danach meist unbrauchbar: Nach einem error folgt in der Regel close. Legen Sie die Logik für den Neuaufbau deshalb in den close-Handler und nicht in den error-Handler, sonst wird der Kanal womöglich doppelt aufgebaut.
Nur ein Handler über onerror: Wer onerror erneut zuweist, überschreibt den vorherigen Handler. Für mehrere unabhängige Handler verwenden Sie addEventListener.
Nicht mit Verbindungsfehlern verwechseln: Probleme mit ICE oder der gesamten Peer-Verbindung melden RTCPeerConnection-Ereignisse wie connectionstatechange oder icecandidateerror, nicht dieses Ereignis.

Siehe auch

RTCDataChannel RTCErrorEvent RTCError RTCPeerConnection.prototype.createDataChannel() RTCDataChannel.readyState RTCDataChannel: bufferedamountlow