ErrorEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface ErrorEvent extends Event

Beschreibung

ErrorEvent ist das Ereignis-Objekt, das der Browser beim error-Ereignis auf window oder in Workern (self bzw. auf dem Worker-Objekt) auslöst, wenn ein Skript einen nicht abgefangenen Laufzeitfehler wirft. Es erweitert Event um die schreibgeschützten Eigenschaften message, filename, lineno, colno und error.

Typischer Einsatz ist eine globale Fehlerbehandlung: Man registriert einen Listener auf window, protokolliert die Fehlerdetails und schickt sie z. B. an einen Monitoring-Dienst. Über event.preventDefault() lässt sich die Standardausgabe in der Konsole unterdrücken.

Wichtig: Fehler beim Laden von Ressourcen (z. B. <img> oder <script src> mit 404) lösen zwar ebenfalls ein error-Ereignis aus, das ist aber ein einfaches Event und kein ErrorEvent; es blubbert nicht, kann aber in der Capture-Phase auf window abgefangen werden. Abgelehnte Promises ohne Handler erzeugen stattdessen ein unhandledrejection-Ereignis (PromiseRejectionEvent).

Mit dem Konstruktor new ErrorEvent(type, options) können eigene Instanzen erzeugt und per dispatchEvent() ausgelöst werden, etwa in Tests.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, in der Regel `"error"` (Konstruktor-Parameter).
$options	ErrorEventInit	{}	Optionales Objekt mit `message` (string), `filename` (string), `lineno` (number), `colno` (number), `error` (any) sowie den `EventInit`-Feldern `bubbles`, `cancelable`, `composed`.

Rückgabewert

Typ

ErrorEvent

Beschreibung

Instanz mit den schreibgeschützten Eigenschaften message, filename, lineno, colno und error.

Beispiele

Globale Fehlerprotokollierung mit addEventListener

window.addEventListener("error", (event) => {
  if (!(event instanceof ErrorEvent)) return; // Ressourcenfehler ignorieren
  const { message, filename, lineno, colno, error } = event;
  console.log(`Fehler: ${message} in ${filename}:${lineno}:${colno}`);
  console.log("Stack:", error?.stack);
});

setTimeout(() => {
  undefinedFunction();
}, 0);

Fehler: Uncaught ReferenceError: undefinedFunction is not defined in https://example.com/app.js:9:3 Stack: ReferenceError: undefinedFunction is not defined ...

Fehler an Monitoring-Dienst senden

const reportError = (event) => {
  const payload = {
    message: event.message,
    source: event.filename,
    line: event.lineno,
    column: event.colno,
    stack: event.error?.stack ?? null,
    url: location.href,
    time: new Date().toISOString()
  };
  navigator.sendBeacon("/api/errors", JSON.stringify(payload));
};

window.addEventListener("error", reportError);
// später wieder entfernen:
// window.removeEventListener("error", reportError);

Fehler in einem Web Worker abfangen

const code = "throw new Error('Kaputt im Worker');";
const blob = new Blob([code], { type: "text/javascript" });
const worker = new Worker(URL.createObjectURL(blob));

worker.onerror = (event) => {
  console.log("Worker-Fehler:", event.message, "Zeile", event.lineno);
  event.preventDefault(); // Konsolen-Standardausgabe unterdrücken
};

Worker-Fehler: Uncaught Error: Kaputt im Worker Zeile 1

ErrorEvent manuell erzeugen (z. B. für Tests)

const err = new Error("Testfehler");
const evt = new ErrorEvent("error", {
  message: err.message,
  filename: "test.js",
  lineno: 42,
  colno: 7,
  error: err,
  cancelable: true
});

window.addEventListener("error", (e) => {
  console.log(e.message, e.lineno, e.error === err);
}, { once: true });

window.dispatchEvent(evt);

Testfehler 42 true

// Wichtig · Fallstricke

Cross-Origin-Skripte: Stammt der Fehler aus einem Skript einer anderen Herkunft ohne crossorigin-Attribut und passende CORS-Header, liefert der Browser aus Sicherheitsgründen nur "Script error.", filename ist leer, lineno/colno sind 0 und error ist null. Abhilfe: <script src="…" crossorigin="anonymous"> plus Access-Control-Allow-Origin.
Signatur-Unterschied bei window.onerror: Der Handler erhält dort nicht das Ereignis-Objekt, sondern fünf Argumente (message, source, lineno, colno, error); return true unterdrückt die Konsolenausgabe. Mit addEventListener bekommt man das ErrorEvent und nutzt preventDefault().
Ladefehler von Ressourcen sind einfache Event-Objekte ohne message – daher mit instanceof ErrorEvent unterscheiden.
Promise-Ablehnungen und Fehler in async-Funktionen landen nicht hier, sondern bei unhandledrejection.
Keine Fehlerdetails ungefiltert per innerHTML ausgeben – Fehlermeldungen können von Nutzereingaben beeinflusst sein (XSS).
error kann jeder geworfene Wert sein (auch Strings), daher error?.stack defensiv abfragen.

Siehe auch

Event Worker Error RTCErrorEvent BlobEvent