SVGElement: error — Ereignis · JavaScript-Referenz

Signatur

svgElement.addEventListener("error", handler)

Beschreibung

Das error-Ereignis eines SVGElement meldet, dass eine vom Element referenzierte externe Ressource nicht geladen werden konnte. Typische Auslöser sind ein SVG-<image>, dessen href auf eine fehlende oder beschädigte Datei zeigt, oder ein SVG-<script>, dessen externe Quelle nicht abrufbar ist. Das Ereignis ist ein einfaches Event und steigt nicht auf (kein Bubbling). Abbrechen lässt es sich ebenfalls nicht.

Registrieren kannst du einen Handler entweder mit addEventListener("error", handler) oder über die Eigenschaft onerror des Elements. Da das Ereignis nicht aufsteigt, musst du den Listener direkt am betroffenen Element registrieren. Alternativ fängst du es in der Capture-Phase an einem übergeordneten Element oder am document ab: addEventListener("error", fn, true).

In der Praxis dient das Ereignis vor allem für Ersatzgrafiken, Fehlerprotokolle und robuste Diagramme bzw. Karten, die externe Bilder in SVG einbinden. Laufzeitfehler in JavaScript-Code, der bereits ausgeführt wird, lösen dagegen kein error am SVG-Element aus. Sie landen bei window.onerror bzw. als ErrorEvent am window.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"error"`.
$handler Pflicht	(event: Event) => void		Callback, das ein einfaches `Event` erhält. `event.target` ist das SVG-Element, dessen Ressource nicht geladen werden konnte.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `capture` oder `signal`. Mit `capture: true` kannst du Fehler zentral an einem Vorfahren abfangen, obwohl das Ereignis nicht aufsteigt.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt mit bubbles === false und cancelable === false.

Beispiele

Ersatzbild für ein fehlerhaftes SVG-<image>

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.querySelector('svg#karte');

const img = document.createElementNS(SVG_NS, 'image');
img.setAttribute('width', '200');
img.setAttribute('height', '120');

img.addEventListener('error', (event) => {
  console.warn('Bild konnte nicht geladen werden:', event.target.getAttribute('href'));
  // Fallback nur einmal setzen, um Endlosschleifen zu vermeiden
  event.target.setAttribute('href', '/img/platzhalter.svg');
}, { once: true });

img.setAttribute('href', '/img/gibt-es-nicht.png');
svg.append(img);

Bild konnte nicht geladen werden: /img/gibt-es-nicht.png

Handler über die onerror-Eigenschaft setzen und wieder entfernen

const logo = document.querySelector('svg image#logo');

logo.onerror = (event) => {
  console.error(`Fehler beim Laden (${event.type}) von`, event.target.id);
  event.target.style.display = 'none';
};

// Später, z. B. nach erfolgreichem Laden, wieder entfernen:
logo.addEventListener('load', () => {
  logo.onerror = null;
  console.log('Logo geladen, onerror entfernt');
});

Fehler beim Laden (error) von logo

Zentrales Fehler-Logging per Capture-Phase und removeEventListener

const diagramm = document.querySelector('svg#diagramm');
const fehler = [];

const onSvgError = (event) => {
  if (event.target instanceof SVGElement) {
    fehler.push({
      tag: event.target.tagName,
      src: event.target.getAttribute('href')
    });
    console.log('SVG-Fehler erfasst:', fehler.at(-1));
  }
};

// error steigt nicht auf, deshalb capture: true
diagramm.addEventListener('error', onSvgError, true);

// Aufräumen, wenn das Diagramm entfernt wird:
const aufraeumen = () => diagramm.removeEventListener('error', onSvgError, true);
setTimeout(aufraeumen, 10_000);

SVG-Fehler erfasst: { tag: 'image', src: 'daten/icon-fehlt.png' }

// Wichtig · Fallstricke

Kein Bubbling: Ein normaler Listener an einem Elternelement oder am <svg>-Wurzelelement erhält das Ereignis nicht. Nutze entweder einen Listener direkt am Element oder capture: true. Wichtig: Bei removeEventListener muss dasselbe capture-Flag angegeben werden, sonst wird der Listener nicht entfernt.
Endlosschleifen: Setzt du im Handler eine Ersatzquelle, die ebenfalls fehlschlägt, wird error erneut ausgelöst. Verwende { once: true } oder ein Kennzeichen, das anzeigt, dass der Fallback schon aktiv ist.
Listener vor dem Laden registrieren: Registriere den Listener, bevor du href setzt bzw. das Element in das DOM einfügst. Sonst kann das Ereignis bereits vorbei sein, bevor der Listener existiert.
Keine Fehlerdetails: Das Ereignis ist ein einfaches Event ohne message oder HTTP-Status. Details liefern nur Netzwerkwerkzeuge oder ein separater fetch()-Aufruf.
Skriptfehler: Laufzeitausnahmen in SVG-Skripten werden als ErrorEvent an window gemeldet, nicht an das SVG-Element.
Sicherheit: Inline-Attribute wie onerror="…" in eingebettetem oder hochgeladenem SVG-Markup sind ein bekannter XSS-Weg (z. B. <image href="x" onerror="alert(1)">). Nicht vertrauenswürdiges SVG vorher bereinigen (z. B. mit DOMPurify), per <img> einbinden (Skripte werden dann nicht ausgeführt) und eine strikte CSP ohne 'unsafe-inline' einsetzen.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Das veraltete SVG-1.1-Ereignis SVGError wird nicht mehr verwendet.

Siehe auch

SVGElement SVGElement: load SVGImageElement HTMLElement: error Window: error EventTarget.addEventListener() EventTarget.removeEventListener()