Worker: messageerror — Ereignis · JavaScript-Referenz

Signatur

worker.addEventListener("messageerror", handler)

Beschreibung

Das Ereignis messageerror wird im Hauptthread am Worker-Objekt ausgelöst, wenn eine Nachricht aus dem Worker (gesendet mit postMessage() im Worker-Kontext) zwar ankommt, aber beim Empfänger nicht deserialisiert werden kann. Das ist ein anderer Fall als ein DataCloneError beim Senden: Dort schlägt die Serialisierung fehl und postMessage() wirft sofort eine Ausnahme. messageerror betrifft dagegen die Deserialisierung auf der Empfängerseite.

In der Praxis kommt das selten vor. Typische Auslöser sind zum Beispiel ein SharedArrayBuffer, der an einen Agenten-Cluster ohne Cross-Origin-Isolation übertragen wird, oder serialisierte Objekte (etwa WebAssembly.Module), die im Zielkontext nicht wiederhergestellt werden können. Das Ereignis ist ein MessageEvent. Seine Eigenschaft data ist dabei in der Regel null, weil sich der Inhalt ja gerade nicht rekonstruieren ließ.

Registrieren kannst du den Handler mit worker.addEventListener("messageerror", handler) oder über die Eigenschaft worker.onmessageerror = handler. Das Ereignis bubbelt nicht und lässt sich nicht abbrechen. Es ist sinnvoll, einen solchen Handler als Absicherung für die Fehlersuche zu registrieren, weil fehlgeschlagene Nachrichten sonst unbemerkt verloren gehen: Das message-Ereignis wird in diesem Fall nicht ausgelöst.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"messageerror"`.
$handler Pflicht	(event: MessageEvent) => void		Callback, der ein `MessageEvent` erhält. `event.data` ist meist `null`, `event.target` ist der betroffene `Worker`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener() hat keinen Rückgabewert. Der Handler bekommt ein MessageEvent übergeben.

Beispiele

Deserialisierungsfehler mit addEventListener protokollieren

const worker = new Worker(new URL('./rechner.js', import.meta.url), { type: 'module' });

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

worker.addEventListener('messageerror', (event) => {
  // event.data ist hier in der Regel null
  console.error('Nachricht vom Worker konnte nicht gelesen werden:', event);
});

worker.postMessage({ aufgabe: 'summe', werte: [1, 2, 3] });

Ergebnis: 6

Mit der on-Property und Aufräumen per removeEventListener

const worker = new Worker('worker.js');

// Variante 1: on-Property (überschreibt einen vorherigen Handler)
worker.onmessageerror = (event) => {
  console.warn('messageerror (on-Property):', event.data);
};

// Variante 2: benannter Listener, später wieder entfernbar
const beiFehler = (event) => {
  console.warn('messageerror (Listener):', event.data);
};
worker.addEventListener('messageerror', beiFehler);

// Beim Beenden aufräumen
const beenden = () => {
  worker.removeEventListener('messageerror', beiFehler);
  worker.onmessageerror = null;
  worker.terminate();
};

setTimeout(beenden, 5000);

Serialisierungsfehler (Senden) vs. messageerror (Empfangen) unterscheiden

const worker = new Worker('worker.js');
const controller = new AbortController();

worker.addEventListener('messageerror', () => {
  console.error('Empfangsseite: Deserialisierung fehlgeschlagen');
}, { signal: controller.signal });

try {
  // Funktionen sind nicht klonbar: das wirft sofort beim Senden
  worker.postMessage({ callback: () => 42 });
} catch (err) {
  console.error('Sendeseite:', err.name);
}

// Später alle Listener auf einmal entfernen
controller.abort();

Sendeseite: DataCloneError

// Wichtig · Fallstricke

Nicht mit error verwechseln: Das Ereignis error am Worker meldet Skriptfehler (Ausnahmen im Worker, Ladefehler). messageerror betrifft nur die Deserialisierung einer Nachricht.
Nicht mit DataCloneError verwechseln: Nicht klonbare Werte wie Funktionen oder DOM-Knoten führen schon beim Senden zu einer Ausnahme in postMessage() und lösen kein messageerror aus.
Richtung beachten: Am Worker-Objekt kommen nur Fehler bei Nachrichten aus dem Worker an. Für die Gegenrichtung registrierst du im Worker-Skript self.addEventListener('messageerror', …) (siehe DedicatedWorkerGlobalScope).
Nachricht geht verloren: Wird messageerror ausgelöst, gibt es für diese Nachricht kein message-Ereignis. Wenn du auf eine Antwort wartest (etwa über ein Promise mit Anfrage-ID), solltest du zusätzlich ein Timeout einbauen.
SharedArrayBuffer: Ohne Cross-Origin-Isolation (Header Cross-Origin-Opener-Policy und Cross-Origin-Embedder-Policy) ist SharedArrayBuffer gar nicht verfügbar oder lässt sich nicht übertragen. Je nach Situation zeigt sich das als Fehler beim Senden oder als messageerror.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt, in Safari erst ab 16.4. In Node.js gibt es das entsprechende Ereignis 'messageerror' an worker_threads.Worker (ab Node.js 14.5).

Siehe auch

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