BroadcastChannel: messageerror — Ereignis · JavaScript-Referenz

Signatur

broadcastChannel.addEventListener("messageerror", handler)

Beschreibung

Das Ereignis messageerror tritt auf, wenn ein BroadcastChannel eine Nachricht empfängt, deren Daten beim Empfänger nicht mit dem Structured-Clone-Algorithmus wiederhergestellt werden können. Statt eines message-Ereignisses bekommt der Empfänger dann ein MessageEvent vom Typ messageerror. Dessen Eigenschaft data ist null.

Einen Handler registrierst du mit addEventListener("messageerror", handler) oder über die Eigenschaft onmessageerror. Das Ereignis steigt nicht auf (bubbles: false) und lässt sich nicht abbrechen.

In der Praxis ist das Ereignis selten, aber es kann vorkommen. Ein Beispiel: Ein SharedArrayBuffer wird zwischen Kontexten verschickt, die nicht zur selben Agent-Cluster-Gruppe gehören. Ein anderes: Ein Objekt lässt sich im empfangenden Kontext nicht wiederherstellen, etwa ein WebAssembly.Module über Prozessgrenzen oder bestimmte plattformspezifische Objekte. Den Handler nutzt du vor allem für Protokollierung und Fehlerdiagnose, oder um den Absender um eine andere Übertragungsform zu bitten.

Wichtig ist die Abgrenzung: Kann ein Wert schon beim Senden nicht serialisiert werden (z. B. Funktionen oder DOM-Knoten), wirft postMessage() beim Absender sofort eine DataCloneError-DOMException. In diesem Fall wird kein messageerror ausgelöst.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname: `"messageerror"`.
$handler Pflicht	(event: MessageEvent) => void		Callback, der ein `MessageEvent` erhält. Wichtige Eigenschaften: `data` (bei diesem Ereignis `null`), `origin`, `lastEventId`, `source` und `ports`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Dem Handler wird ein MessageEvent übergeben.

Beispiele

Deserialisierungsfehler mit addEventListener protokollieren

const channel = new BroadcastChannel('app-sync');

channel.addEventListener('message', (event) => {
  console.log('Nachricht:', event.data);
});

channel.addEventListener('messageerror', (event) => {
  // data ist bei messageerror immer null
  console.error('Nachricht konnte nicht gelesen werden', {
    origin: event.origin,
    data: event.data
  });
});

Nachricht konnte nicht gelesen werden { origin: 'https://example.com', data: null }

Handler über die onmessageerror-Eigenschaft setzen und wieder entfernen

const channel = new BroadcastChannel('warenkorb');

channel.onmessageerror = (event) => {
  console.warn('Ungültige Warenkorb-Nachricht empfangen:', event.type);
};

// Später: Handler entfernen und Kanal schließen
const cleanup = () => {
  channel.onmessageerror = null;
  channel.close();
};

window.addEventListener('pagehide', cleanup);

Ungültige Warenkorb-Nachricht empfangen: messageerror

Listener per AbortSignal entfernen und Absender um Neuversand bitten

const channel = new BroadcastChannel('daten');
const controller = new AbortController();

channel.addEventListener('messageerror', () => {
  // Absender um eine einfache JSON-Variante bitten
  channel.postMessage({ type: 'resend-request', format: 'json' });
}, { signal: controller.signal });

// Sendefehler treten dagegen synchron beim Absender auf:
try {
  channel.postMessage({ callback: () => {} });
} catch (err) {
  console.log(err.name);
}

// Listener entfernen
controller.abort();

DataCloneError

// Wichtig · Fallstricke

Nicht mit Sendefehlern verwechseln: Werte, die sich nicht klonen lassen (Funktionen, DOM-Knoten, Symbole), lösen schon beim Senden eine DataCloneError-Ausnahme in postMessage() aus. Solche Aufrufe fängst du mit try…catch ab, nicht mit messageerror.
event.data ist null: Die fehlerhafte Nachricht lässt sich nicht wiederherstellen. Wenn du Diagnosedaten brauchst, schicke eigene Metadaten, etwa eine Nachrichten-ID, in einer separaten, einfachen Nachricht mit.
Selten auszulösen: Im Alltag ist das Ereignis schwer zu provozieren. Ein typischer Auslöser ist ein SharedArrayBuffer ohne Cross-Origin-Isolation (COOP/COEP). Für Tests eignen sich deshalb eher Mocks.
Sicherheit: BroadcastChannel verbindet nur Kontexte mit gleichem Ursprung. Trotzdem solltest du empfangene Daten prüfen, bevor du sie weiterverarbeitest. Andere Tabs können veraltete oder fremde Code-Versionen ausführen.
Kompatibilität: Wird in allen aktuellen Browsern unterstützt, auch in Web Workern. Safari unterstützt BroadcastChannel erst ab Version 15.4. In Node.js ist BroadcastChannel ab Version 15.4 global verfügbar und kennt ebenfalls messageerror.
Rufe close() auf, wenn du den Kanal nicht mehr brauchst. Danach kommen keine Ereignisse mehr an.

Siehe auch

BroadcastChannel BroadcastChannel.prototype.postMessage() BroadcastChannel.prototype.close() MessageEvent BroadcastChannel: message