SharedWorker: error — Ereignis · JavaScript-Referenz

Signatur

sharedWorker.addEventListener("error", handler)

Beschreibung

Das error-Ereignis tritt am SharedWorker-Objekt im erzeugenden Dokument auf, wenn beim Start des Workers ein Fehler passiert. Typische Ursachen sind ein Netzwerkfehler (404, Server nicht erreichbar), ein falscher MIME-Typ, ein Verstoß gegen die Same-Origin-Richtlinie oder die Content Security Policy (CSP) und ein Syntaxfehler im Worker-Skript.

Sie können den Handler auf zwei Arten registrieren: mit sharedWorker.addEventListener("error", handler) oder über die Eigenschaft sharedWorker.onerror = handler. Das Ereignis ist ein gewöhnliches Event, kein ErrorEvent. Es enthält also keine Felder wie message, filename oder lineno. Es steigt nicht im DOM auf (kein Bubbling) und lässt sich nicht abbrechen.

Anders als bei einem dedizierten Worker werden Laufzeitfehler im Shared Worker nicht an die verbundenen Dokumente weitergegeben. Solche Fehler müssen Sie im Worker selbst behandeln, zum Beispiel mit self.onerror bzw. self.addEventListener("error", …) im SharedWorkerGlobalScope. Danach können Sie sie bei Bedarf über port.postMessage() an die Seiten senden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, hier immer `"error"`.
$handler Pflicht	(event: Event) => void		Callback, das bei einem Startfehler aufgerufen wird. Es erhält ein einfaches `Event`-Objekt mit `event.target === sharedWorker`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal` (zum Entfernen mit einem `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt.

Beispiele

Startfehler mit addEventListener abfangen

const worker = new SharedWorker('/js/gibt-es-nicht.js');

worker.addEventListener('error', (event) => {
  // Einfaches Event, kein ErrorEvent: kein message/lineno
  console.error('SharedWorker konnte nicht gestartet werden:', event.type);
  document.querySelector('#status').textContent = 'Synchronisierung nicht verfügbar';
});

worker.port.start();

SharedWorker konnte nicht gestartet werden: error

on-Property nutzen und Handler später entfernen

const worker = new SharedWorker('/js/sync-worker.js', { name: 'sync' });

const onWorkerError = () => {
  console.warn('Fallback: Sync ohne SharedWorker');
  startLocalSync();
};

// Variante 1: on-Property
worker.onerror = onWorkerError;

// Variante 2: Listener, der nach einer ersten Nachricht wieder entfernt wird
worker.addEventListener('error', onWorkerError);
worker.port.onmessage = (e) => {
  if (e.data === 'ready') {
    worker.removeEventListener('error', onWorkerError);
    worker.onerror = null;
    console.log('Worker läuft');
  }
};

function startLocalSync() { /* ... */ }

Worker läuft

Laufzeitfehler im Worker selbst behandeln und an die Seiten melden

// sync-worker.js (SharedWorkerGlobalScope)
const ports = new Set();

self.addEventListener('connect', (e) => {
  const port = e.ports[0];
  ports.add(port);
  port.postMessage('ready');
  port.onmessage = (msg) => {
    if (msg.data === 'crash') throw new Error('Absichtlicher Fehler');
  };
});

// Laufzeitfehler kommen NICHT als error-Event am SharedWorker-Objekt an
self.addEventListener('error', (event) => {
  for (const port of ports) {
    port.postMessage({ type: 'worker-error', message: event.message });
  }
});

// Seite:
// worker.port.onmessage = (e) => {
//   if (e.data?.type === 'worker-error') console.error('Worker-Fehler:', e.data.message);
// };

Worker-Fehler: Uncaught Error: Absichtlicher Fehler

// Wichtig · Fallstricke

Kein ErrorEvent: Am SharedWorker-Objekt kommt nur ein einfaches Event an. Details zur Fehlerursache stehen nur in der Entwicklerkonsole des Browsers, nicht im Ereignis.
Laufzeitfehler: Fehler, die nach dem erfolgreichen Start auftreten, werden nicht an die verbundenen Seiten weitergegeben. Behandeln Sie sie im Worker (self.onerror) und melden Sie sie über MessagePort weiter.
Konstruktor-Ausnahmen: Eine ungültige URL oder eine fremde Herkunft (Cross-Origin) lösen meist schon beim Aufruf von new SharedWorker() eine SecurityError- oder SyntaxError-DOMException aus. Das error-Ereignis tritt dann nicht auf, darum zusätzlich try…catch verwenden.
CSP: Die Direktive worker-src (Fallback script-src) kann das Laden blockieren. Das führt ebenfalls zum error-Ereignis.
Kompatibilität: SharedWorker fehlt in Chrome für Android und in einigen WebViews. Safari unterstützt die Schnittstelle erst wieder ab Version 16. Vorher mit 'SharedWorker' in window prüfen.
Eine Zuweisung an onerror überschreibt einen vorherigen Handler. addEventListener erlaubt dagegen mehrere Listener.

Siehe auch

ServiceWorker: error Worker: error MediaRecorder: error Sensor: error SourceBuffer: error