WorkerGlobalScope: error — Ereignis · JavaScript-Referenz

Signatur

self.addEventListener("error", handler)

Beschreibung

Das error-Ereignis der WorkerGlobalScope-Schnittstelle tritt im Worker selbst auf, sobald dort eine Ausnahme nicht von einem try...catch abgefangen wird, etwa ein throw in einem message-Handler, ein TypeError in einem Timer-Callback oder ein Fehler in einem Skript, das über importScripts() geladen wurde. Das Ereignisobjekt ist ein ErrorEvent mit den Eigenschaften message, filename, lineno, colno und error.

Einen Handler kannst du auf zwei Arten registrieren: mit self.addEventListener("error", handler) oder über die Eigenschaft self.onerror. Die Eigenschaft hat eine Besonderheit, die sie mit window.onerror teilt: Der Handler bekommt fünf einzelne Argumente (message, filename, lineno, colno, error) statt eines Ereignisobjekts. Gibt er true zurück, gilt der Fehler als behandelt.

Wird der Fehler im Worker nicht als behandelt markiert (also weder event.preventDefault() aufgerufen noch true aus onerror zurückgegeben), leitet der Browser ihn als error-Ereignis an das zugehörige Worker-Objekt im Hauptthread weiter und meldet ihn zusätzlich in der Konsole. So kannst du selbst entscheiden, ob Fehler direkt im Worker protokolliert werden oder beim aufrufenden Code landen.

Typische Einsatzfälle sind zentrales Fehler-Logging im Worker, das Zurücksenden strukturierter Fehlermeldungen per postMessage() und das Aufräumen von Ressourcen, bevor der Worker in einem inkonsistenten Zustand weiterläuft.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"error"`.
$handler Pflicht	(event: ErrorEvent) => void		Callback, der ein `ErrorEvent` mit `message`, `filename`, `lineno`, `colno` und `error` erhält. Mit `event.preventDefault()` verhinderst du die Weiterleitung an den Hauptthread.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Bei self.onerror bedeutet der Rückgabewert true, dass der Fehler behandelt ist und nicht weitergeleitet wird.

Beispiele

Fehler im Worker protokollieren und an den Hauptthread melden

// worker.js
self.addEventListener("error", (event) => {
  // Strukturierte Fehlermeldung an den Hauptthread schicken
  self.postMessage({
    type: "worker-error",
    message: event.message,
    ort: `${event.filename}:${event.lineno}:${event.colno}`
  });
  // Standardverhalten (Weiterleitung als Worker-error-Event) unterdrücken
  event.preventDefault();
});

self.addEventListener("message", (e) => {
  // Absichtlicher Fehler: undefined hat keine Eigenschaft "length"
  const laenge = e.data.liste.length;
  self.postMessage({ type: "ergebnis", laenge });
});

{ type: "worker-error", message: "Uncaught TypeError: Cannot read properties of undefined (reading 'length')", ort: ".../worker.js:15:30" }

Variante mit self.onerror und Rückgabewert true

// worker.js
self.onerror = (message, filename, lineno, colno, error) => {
  console.warn("Worker-Fehler:", message, "in Zeile", lineno);
  console.warn("Stack:", error?.stack);
  return true; // Fehler gilt als behandelt, keine Weiterleitung
};

setTimeout(() => {
  throw new Error("Timer fehlgeschlagen");
}, 100);

Worker-Fehler: Uncaught Error: Timer fehlgeschlagen in Zeile 8

Komplett lauffähig mit Blob-Worker: Weiterleitung an den Hauptthread

// Hauptthread: Worker-Code als Blob erzeugen
const code = `
  self.addEventListener("error", (event) => {
    console.log("[Worker] gesehen:", event.message);
    // kein preventDefault(): Fehler geht weiter an den Hauptthread
  });
  throw new Error("Kaputt beim Start");
`;
const url = URL.createObjectURL(new Blob([code], { type: "text/javascript" }));
const worker = new Worker(url);

worker.addEventListener("error", (event) => {
  console.log("[Main] empfangen:", event.message);
  event.preventDefault(); // Konsolenmeldung im Hauptthread unterdrücken
  URL.revokeObjectURL(url);
});

[Worker] gesehen: Uncaught Error: Kaputt beim Start [Main] empfangen: Uncaught Error: Kaputt beim Start

// Wichtig · Fallstricke

Unterschiedliche Signaturen: self.onerror bekommt (message, filename, lineno, colno, error), mit addEventListener erhältst du dagegen ein ErrorEvent. Behandelt wird der Fehler bei onerror durch return true, bei addEventListener durch event.preventDefault(). Ein return true im Listener hat keine Wirkung.
Promises: Abgelehnte Promises ohne catch lösen kein error-Ereignis aus. Dafür gibt es das Ereignis unhandledrejection. Fehler in async-Funktionen landen ebenfalls dort.
Ladefehler: Kann die Worker-Skriptdatei gar nicht geladen werden (404, falscher MIME-Typ, CSP-Blockade), läuft im Worker kein Code. Das Ereignis tritt dann nur am Worker-Objekt im Hauptthread auf, meist ohne message.
Cross-Origin: Bei Skripten von fremden Origins, die per importScripts() ohne CORS geladen werden, können message, filename und lineno aus Sicherheitsgründen geschwärzt sein („Script error.“).
Das Ereignis steigt nicht auf (bubbelt nicht). Nach einem nicht abgefangenen Fehler läuft der Worker weiter, er wird nicht automatisch beendet.
Gilt gleichermaßen für DedicatedWorkerGlobalScope und SharedWorkerGlobalScope und ist in allen modernen Browsern verfügbar. Service Worker (ServiceWorkerGlobalScope) erben es ebenfalls, dort gibt es aber kein Worker-Objekt, an das weitergeleitet werden könnte.

Siehe auch

WorkerGlobalScope ErrorEvent DedicatedWorkerGlobalScope.postMessage() EventSource: error WorkerGlobalScope: online WorkerGlobalScope: securitypolicyviolation