Window: error — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("error", handler)

Beschreibung

Das error-Ereignis auf window ist der zentrale Punkt, um nicht abgefangene JavaScript-Fehler global zu erfassen. Wirft ein Skript eine Ausnahme, die von keinem try...catch behandelt wird, erzeugt der Browser ein ErrorEvent mit Fehlermeldung, Dateiname, Zeile, Spalte und dem eigentlichen Fehlerobjekt. Damit lassen sich Fehler protokollieren, an einen Monitoring-Dienst senden oder dem Nutzer eine freundliche Meldung anzeigen.

Es gibt zwei Registrierungswege: window.addEventListener("error", handler) erhält ein ErrorEvent-Objekt; die Eigenschaft window.onerror hat dagegen aus historischen Gründen eine abweichende Signatur mit fünf Einzelargumenten (message, source, lineno, colno, error). Gibt onerror true zurück, wird die Standardausgabe in der Konsole unterdrückt; bei addEventListener erreicht man dasselbe mit event.preventDefault().

Ladefehler von Ressourcen (z. B. <img>, <script>, <link>) lösen das error-Ereignis am jeweiligen Element aus. Dieses Ereignis blubbert nicht nach oben, lässt sich aber auf window in der Capture-Phase (addEventListener(..., true)) abfangen. Es ist dann ein einfaches Event ohne Fehlerdetails; event.target verweist auf das betroffene Element.

Abgelehnte Promises ohne catch lösen nicht error aus, sondern das separate Ereignis unhandledrejection. Für ein vollständiges Fehler-Monitoring sollten beide Ereignisse behandelt werden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"error"`.
$handler Pflicht	(event: ErrorEvent \| Event) => void		Callback. Bei Skriptfehlern ein `ErrorEvent` mit `message`, `filename`, `lineno`, `colno` und `error`; bei Ressourcen-Ladefehlern (nur Capture-Phase) ein einfaches `Event` mit `target` = betroffenes Element.
$options / useCapture	boolean \| AddEventListenerOptions	false	Mit `true` bzw. `{ capture: true }` werden zusätzlich Ladefehler von Elementen erfasst, da diese nicht blubbern.
$onerror(message, source, lineno, colno, error)	(string \| Event, string, number, number, Error) => boolean \| void		Alternative über `window.onerror`: Fehlermeldung, Skript-URL, Zeile, Spalte und Fehlerobjekt als Einzelargumente. Rückgabe `true` unterdrückt die Konsolenausgabe.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Bei window.onerror bewirkt ein Rückgabewert true, dass der Browser den Fehler nicht zusätzlich in der Konsole meldet (entspricht event.preventDefault()).

Beispiele

Globale Fehler an einen Monitoring-Endpunkt senden

window.addEventListener("error", (event) => {
  const payload = {
    message: event.message,
    file: event.filename,
    line: event.lineno,
    column: event.colno,
    stack: event.error?.stack ?? null,
    url: location.href,
  };
  // sendBeacon funktioniert auch beim Verlassen der Seite zuverlässig
  navigator.sendBeacon("/api/client-errors", JSON.stringify(payload));
});

// Provozierter Fehler
setTimeout(() => {
  undefinedFunction();
}, 0);

POST /api/client-errors mit {"message":"Uncaught ReferenceError: undefinedFunction is not defined", ...}

window.onerror mit fünf Argumenten und Unterdrückung der Konsolenausgabe

window.onerror = (message, source, lineno, colno, error) => {
  console.info(`Abgefangen: ${message} (${source}:${lineno}:${colno})`);
  console.info("Typ:", error?.name);
  return true; // Standard-Fehlermeldung in der Konsole unterdrücken
};

setTimeout(() => {
  JSON.parse("{kaputt");
}, 0);

Abgefangen: Uncaught SyntaxError: Expected property name or '}' in JSON at position 1 (https://example.com/app.js:9:8) Typ: SyntaxError

Ladefehler von Bildern und Skripten in der Capture-Phase erfassen

window.addEventListener(
  "error",
  (event) => {
    // Ressourcenfehler: target ist das Element, nicht window
    if (event.target !== window && event.target instanceof HTMLElement) {
      const el = event.target;
      console.warn(`Ressource fehlgeschlagen: <${el.tagName.toLowerCase()}>`, el.src || el.href);
      if (el instanceof HTMLImageElement) {
        el.src = "/img/platzhalter.svg"; // Fallback-Bild
      }
    }
  },
  true // Capture! Sonst wird der Fehler nicht erreicht
);

const img = document.createElement("img");
img.src = "/gibt-es-nicht.png";
document.body.append(img);

Ressource fehlgeschlagen: <img> https://example.com/gibt-es-nicht.png

Handler wieder entfernen

const onGlobalError = (event) => {
  console.log("Fehler:", event.message);
};

window.addEventListener("error", onGlobalError);

// Später, z. B. beim Abbau eines Test-Setups
window.removeEventListener("error", onGlobalError);

// Alternativ Property-Variante zurücksetzen
window.onerror = null;

Siehe auch

Window: blur Window: focus Window: load Window: resize Window: unload AbortSignal: abort Element: paste