HTMLElement: error — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("error", handler)

Beschreibung

Das error-Ereignis tritt auf Elementen auf, die eine externe Ressource laden, etwa <img>, <script>, <link>, <iframe> (eingeschränkt), <video>/<audio> (über <source> bzw. media.error) oder <object>. Ausgelöst wird es, wenn der Ladevorgang fehlschlägt (Netzwerkfehler, HTTP-404, CORS-Ablehnung) oder die Ressource zwar geladen wurde, aber nicht nutzbar ist (z. B. kaputtes Bildformat).

Registrieren lässt sich ein Handler per element.addEventListener("error", handler) oder über die Eigenschaft element.onerror = handler. Das Ereignis ist ein einfaches Event (kein ErrorEvent), bubbelt nicht und ist nicht abbrechbar. Wer Ladefehler zentral abfangen will, muss den Listener daher in der Capture-Phase auf window oder document registrieren.

Typische Anwendungsfälle sind Ersatzbilder (Fallback) für defekte Bild-URLs, das Nachladen eines Skripts von einem alternativen CDN, Fehler-Monitoring (Tracking fehlgeschlagener Ressourcen) sowie das saubere Zurücksetzen einer Lade-Anzeige.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier `"error"`.
$handler Pflicht	(event: Event) => void		Callback, der ein einfaches `Event`-Objekt erhält; `event.target` ist das betroffene Element.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `capture`, `once` oder `signal`. Für zentrale Überwachung `{ capture: true }` verwenden, da das Ereignis nicht bubbelt.

Rückgabewert

Typ

void

Beschreibung

addEventListener liefert nichts zurück. Der Handler erhält ein Event mit type === "error".

Beispiele

Ersatzbild bei defekter Bild-URL (addEventListener)

const img = document.createElement('img');

img.addEventListener('error', () => {
  console.warn(`Bild nicht ladbar: ${img.src}`);
  img.src = '/images/platzhalter.png';
}, { once: true }); // once verhindert Endlosschleife, falls auch der Platzhalter fehlt

img.src = '/images/gibt-es-nicht.jpg';
document.body.append(img);

Bild nicht ladbar: https://example.com/images/gibt-es-nicht.jpg

Skript mit CDN-Fallback per onerror-Eigenschaft

const loadScript = (src) => new Promise((resolve, reject) => {
  const script = document.createElement('script');
  script.src = src;
  script.onload = () => resolve(src);
  script.onerror = () => {
    script.remove();
    reject(new Error(`Laden fehlgeschlagen: ${src}`));
  };
  document.head.append(script);
});

const init = async () => {
  try {
    await loadScript('https://cdn-a.example.com/lib.js');
  } catch (err) {
    console.warn(err.message);
    await loadScript('/vendor/lib.js'); // lokaler Fallback
  }
  console.log('Bibliothek bereit');
};

init();

Laden fehlgeschlagen: https://cdn-a.example.com/lib.js Bibliothek bereit

Zentrales Monitoring aller Ressourcenfehler (Capture-Phase)

const onResourceError = (event) => {
  const el = event.target;
  if (el instanceof HTMLElement) {
    const url = el.src || el.href || '(unbekannt)';
    console.error(`Ressourcenfehler <${el.tagName.toLowerCase()}>: ${url}`);
    // navigator.sendBeacon('/log', JSON.stringify({ url }));
  }
};

// capture: true ist nötig, weil error nicht bubbelt
window.addEventListener('error', onResourceError, true);

// Später wieder entfernen – gleiche capture-Angabe verwenden!
const stopMonitoring = () => window.removeEventListener('error', onResourceError, true);

Ressourcenfehler <img>: https://example.com/logo-alt.png

// Wichtig · Fallstricke

Kein Bubbling: Ein Listener auf document oder window ohne capture: true erfasst Ressourcenfehler von Elementen nicht. window.onerror (für JS-Laufzeitfehler, mit ErrorEvent) ist ein anderes Ereignis.
Keine Fehlerdetails: Aus Sicherheitsgründen gibt es weder HTTP-Status noch Meldung. Wer Details braucht, prüft die URL separat mit fetch() oder nutzt die Resource Timing API.
Endlosschleifen: Setzt der Handler ein Ersatzbild, das ebenfalls fehlt, löst dies erneut error aus. Abhilfe: { once: true } oder img.onerror = null vor dem Umsetzen von src.
Handler früh registrieren: Den Listener vor dem Setzen von src anhängen; bei bereits im HTML stehenden Elementen kann der Fehler vor Ausführung des Skripts passiert sein – dann img.complete && img.naturalWidth === 0 prüfen.
Medien: Bei <video>/<audio> mit <source>-Kindern feuert error auf dem jeweiligen <source>; Details liefert media.error (MediaError).
iframe: Zuverlässige error-Ereignisse gibt es bei <iframe> praktisch nicht; eine 404-Seite lädt aus Browsersicht „erfolgreich“.
Sicherheit: Inline-Attribute wie <img onerror=\"...\"> sind ein klassischer XSS-Vektor, wenn nutzergenerierte Inhalte per innerHTML eingefügt werden. Inline-Handler werden zudem durch eine strikte CSP (ohne 'unsafe-inline') blockiert – besser addEventListener verwenden.
Browser-Kompatibilität: in allen modernen Browsern seit langem unterstützt.

Siehe auch

EventTarget.addEventListener() EventTarget.removeEventListener() HTMLImageElement ErrorEvent MediaError