ServiceWorkerGlobalScope: messageerror — Ereignis · JavaScript-Referenz

Signatur

self.addEventListener("messageerror", handler)

Beschreibung

Das messageerror-Ereignis der Schnittstelle ServiceWorkerGlobalScope wird ausgelöst, wenn der Service Worker eine Nachricht erhält, die sich nicht deserialisieren lässt. Das kommt vor, wenn eine Seite (ein Client) mit ServiceWorker.postMessage() Daten schickt, die zwar auf der Senderseite serialisiert wurden, aber im Kontext des Service Workers nicht wiederhergestellt werden können. Ein typisches Beispiel ist ein geteiltes Objekt wie ein SharedArrayBuffer, das nicht über Agent-Cluster-Grenzen übertragen werden darf.

Statt eines message-Ereignisses bekommt der Service Worker dann ein messageerror-Ereignis vom Typ ExtendableMessageEvent. Die Eigenschaft data ist in diesem Fall null. Über source und origin lässt sich aber feststellen, von welchem Client die fehlerhafte Nachricht kam.

Den Handler registrierst du mit self.addEventListener("messageerror", handler) oder über die Eigenschaft self.onmessageerror. Er eignet sich gut, um Fehler zu protokollieren oder dem Absender über event.source.postMessage() zu melden, dass seine Nachricht nicht angekommen ist. Das Ereignis lässt sich nicht abbrechen und steigt nicht auf (kein Bubbling).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, immer `"messageerror"`.
$handler Pflicht	(event: ExtendableMessageEvent) => void		Callback-Funktion. Bekommt ein `ExtendableMessageEvent` mit `data` (hier `null`), `origin`, `lastEventId`, `source` (`Client`, `ServiceWorker` oder `MessagePort`) und `ports`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen, z. B. `{ once: true }` oder ein `signal` zum Entfernen des Listeners.

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Der Handler bekommt ein ExtendableMessageEvent übergeben.

Beispiele

Fehlerhafte Nachrichten im Service Worker protokollieren

// sw.js
self.addEventListener('messageerror', (event) => {
  console.error('Nachricht konnte nicht deserialisiert werden', {
    origin: event.origin,
    sourceId: event.source?.id,
    data: event.data // immer null
  });
});

Nachricht konnte nicht deserialisiert werden { origin: "https://example.com", sourceId: "a1b2...", data: null }

Den Absender über das Problem informieren

// sw.js
self.addEventListener('messageerror', (event) => {
  // event.waitUntil verlängert die Lebensdauer des Workers, bis die Antwort gesendet ist
  event.waitUntil((async () => {
    if (event.source && 'postMessage' in event.source) {
      event.source.postMessage({
        type: 'MESSAGE_ERROR',
        text: 'Deine Nachricht konnte nicht verarbeitet werden.'
      });
    }
  })());
});

// Seite (main.js)
navigator.serviceWorker.addEventListener('message', (event) => {
  if (event.data?.type === 'MESSAGE_ERROR') {
    console.warn(event.data.text);
  }
});

Deine Nachricht konnte nicht verarbeitet werden.

Alternative über die on-Property und Aufräumen

// sw.js
const onError = (event) => {
  console.warn('messageerror von', event.origin);
};

// Variante 1: on-Property (überschreibt einen vorherigen Handler)
self.onmessageerror = onError;

// Variante 2: addEventListener und später wieder entfernen
self.addEventListener('messageerror', onError);
self.removeEventListener('messageerror', onError);

messageerror von https://example.com

// Wichtig · Fallstricke

data ist null: Bei messageerror kommt der Nachrichteninhalt nie an. Du kannst die Nachricht also nicht aus dem Ereignis wiederherstellen, sondern musst den Absender bitten, sie noch einmal in einem anderen Format zu schicken.
Nicht mit Serialisierungsfehlern beim Senden verwechseln: Werte, die sich gar nicht klonen lassen (z. B. Funktionen oder DOM-Knoten), führen schon beim Aufruf von postMessage() auf der Senderseite zu einer DataCloneError-Ausnahme. messageerror tritt nur auf, wenn die Deserialisierung beim Empfänger fehlschlägt.
Registrierung auf oberster Ebene: Service Worker werden beendet, wenn sie untätig sind. Registriere Handler deshalb synchron beim ersten Ausführen des Skripts und nicht erst in asynchronem Code, sonst gehen Ereignisse verloren.
Herkunft prüfen: Kontrolliere event.origin bzw. event.source, bevor du antwortest, und schicke keine sensiblen Fehlerdetails an Clients zurück.
Kompatibilität: Wird in aktuellen Versionen von Chromium, Firefox und Safari (ab 16.4) unterstützt. In älteren Browsern fehlt das Ereignis, dort gehen solche Nachrichten ohne Meldung verloren.

Siehe auch

ServiceWorkerGlobalScope: message ServiceWorkerGlobalScope ExtendableMessageEvent ServiceWorker.prototype.postMessage() Client.prototype.postMessage() Navigation: navigateerror