DedicatedWorkerGlobalScope: messageerror — Ereignis · JavaScript-Referenz

Signatur

self.addEventListener("messageerror", handler)

Beschreibung

Das Event messageerror wird auf dem globalen Objekt eines Dedicated Workers (self bzw. DedicatedWorkerGlobalScope) ausgelöst, wenn der Hauptthread per worker.postMessage() eine Nachricht geschickt hat, die im Worker nicht deserialisiert werden kann. Das normale message-Event wird in diesem Fall nicht ausgelöst. Stattdessen kommt messageerror mit einem MessageEvent, dessen data in der Regel null ist.

Wichtig ist der Unterschied zu einem Fehler beim Serialisieren. Enthält die Nachricht etwa eine Funktion oder einen DOM-Knoten, wirft schon postMessage() beim Absender eine DataCloneError-Ausnahme, und es gibt kein Event. messageerror tritt nur auf, wenn die Serialisierung geklappt hat, das Deserialisieren auf der Empfängerseite aber scheitert. Das kommt selten vor, zum Beispiel wenn ein SharedArrayBuffer in einen Kontext ohne Cross-Origin-Isolation geschickt wird, wenn bestimmte WebAssembly.Module-Objekte nicht übertragbar sind oder wenn der Speicher erschöpft ist.

Einen Listener registrierst du mit self.addEventListener("messageerror", handler) oder über die Eigenschaft self.onmessageerror. Das Event lässt sich nicht abbrechen und steigt nicht auf. Es eignet sich vor allem zum Protokollieren und um dem Hauptthread zu melden, dass eine Nachricht verloren gegangen ist.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Event-Typ, hier immer `"messageerror"`.
$handler Pflicht	(event: MessageEvent) => void		Callback-Funktion, die ein `MessageEvent` erhält. `event.data` ist meist `null`. `event.origin`, `event.ports` usw. sind trotzdem vorhanden.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal` (AbortSignal zum späteren Entfernen).

Beispiele

Listener im Worker mit addEventListener

// worker.js
self.addEventListener("message", (event) => {
  console.log("Nachricht erhalten:", event.data);
});

self.addEventListener("messageerror", (event) => {
  console.error("Nachricht konnte nicht deserialisiert werden:", event);
  // Hauptthread über den Verlust informieren
  self.postMessage({ type: "error", reason: "deserialize-failed" });
});

Nachricht konnte nicht deserialisiert werden: MessageEvent {type: "messageerror", data: null, ...}

Äquivalent über die on-Property

// worker.js
self.onmessageerror = (event) => {
  console.warn("messageerror im Worker, data =", event.data);
};

// Handler wieder entfernen
// self.onmessageerror = null;

messageerror im Worker, data = null

Listener mit removeEventListener bzw. AbortSignal entfernen

// worker.js
const onMessageError = (event) => {
  console.error("Fehlerhafte Nachricht empfangen");
};

self.addEventListener("messageerror", onMessageError);

// später, z. B. beim Aufräumen:
self.removeEventListener("messageerror", onMessageError);

// Alternative mit AbortController
const controller = new AbortController();
self.addEventListener("messageerror", onMessageError, { signal: controller.signal });
controller.abort(); // entfernt den Listener

Hauptthread: Serialisierungsfehler vs. messageerror unterscheiden

// main.js
const worker = new Worker("worker.js");

try {
  // Funktionen sind nicht klonbar -> Fehler schon beim Senden
  worker.postMessage({ callback: () => {} });
} catch (err) {
  console.log(err.name); // kein messageerror im Worker!
}

worker.addEventListener("message", ({ data }) => {
  if (data?.type === "error") {
    console.warn("Worker meldet verlorene Nachricht:", data.reason);
  }
});

DataCloneError

// Wichtig · Fallstricke

Nicht mit DataCloneError verwechseln: Nicht klonbare Werte wie Funktionen, DOM-Knoten oder Symbole lösen schon beim Absender in postMessage() eine Ausnahme aus. messageerror kommt nur, wenn das Deserialisieren beim Empfänger scheitert.
Richtung beachten: Dieses Event betrifft Nachrichten, die vom Hauptthread an den Worker gehen. Für die Gegenrichtung gibt es messageerror auf dem Worker-Objekt im Hauptthread.
Ein typischer Auslöser ist SharedArrayBuffer ohne Cross-Origin-Isolation (COOP/COEP-Header). Prüfe self.crossOriginIsolated.
In event.data stehen keine verwertbaren Daten. Die ursprüngliche Nachricht lässt sich nicht wiederherstellen, deshalb ist eigene Fehlerbehandlung (z. B. erneutes Senden) nötig.
Das Event lässt sich weder abbrechen noch steigt es auf. Wird kein Handler registriert, geht die Nachricht ohne jede Meldung verloren.
Kompatibilität: unterstützt von Chrome 60+, Firefox 57+, Safari 16.4+ und Edge 79+.

Siehe auch

DedicatedWorkerGlobalScope: message DedicatedWorkerGlobalScope.postMessage() Worker: messageerror Worker.postMessage() MessageEvent DedicatedWorkerGlobalScope