HTMLMediaElement: error — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("error", handler)

Beschreibung

Das error-Ereignis eines HTMLMediaElement (also <audio> und <video>) tritt auf, wenn beim Laden oder Abspielen der Medienressource ein Fehler passiert. Typische Ursachen sind Netzwerkabbrüche, ein nicht unterstütztes Format oder Codec, beschädigte Daten oder eine ungültige bzw. nicht erreichbare URL.

Das Ereignis selbst ist ein einfaches Event ohne Zusatzdaten. Die eigentliche Fehlerinformation steht in der Eigenschaft element.error, einem MediaError-Objekt mit code (MEDIA_ERR_ABORTED = 1, MEDIA_ERR_NETWORK = 2, MEDIA_ERR_DECODE = 3, MEDIA_ERR_SRC_NOT_SUPPORTED = 4) und einer optionalen, browserabhängigen message.

Den Handler registriert man mit addEventListener("error", handler) oder über die Eigenschaft onerror. Das Ereignis ist nicht abbrechbar und steigt nicht auf (kein Bubbling). Man nutzt es, um Nutzern eine verständliche Fehlermeldung zu zeigen, auf eine Ersatzquelle umzuschalten oder Fehler zu protokollieren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"error"`.
$handler Pflicht	(event: Event) => void		Callback, das beim Fehler aufgerufen wird. Details stehen in `event.target.error` (`MediaError`).
$options	boolean\|AddEventListenerOptions	false	Optionen wie `once`, `signal` oder `capture`. `capture: true` ist nötig, um das nicht aufsteigende Ereignis an einem Elternelement abzufangen.

Rückgabewert

Typ

void

Beschreibung

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

Beispiele

Fehlercode auswerten und Meldung anzeigen

const video = document.querySelector('video');

const meldungen = {
  1: 'Laden wurde abgebrochen.',
  2: 'Netzwerkfehler beim Laden des Videos.',
  3: 'Das Video konnte nicht dekodiert werden.',
  4: 'Format oder Quelle wird nicht unterstützt.'
};

video.addEventListener('error', () => {
  const { code, message } = video.error;
  console.error(`MediaError ${code}: ${meldungen[code]}`, message);
});

video.src = 'https://example.com/gibt-es-nicht.mp4';

MediaError 4: Format oder Quelle wird nicht unterstützt.

Auf Ersatzquelle umschalten (onerror-Property)

const audio = new Audio();
const quellen = ['/media/podcast.opus', '/media/podcast.mp3'];
let index = 0;

audio.onerror = () => {
  index += 1;
  if (index < quellen.length) {
    console.warn(`Quelle fehlgeschlagen, versuche ${quellen[index]}`);
    audio.src = quellen[index];
  } else {
    console.error('Keine Quelle abspielbar.');
    audio.onerror = null; // Handler entfernen
  }
};

audio.src = quellen[index];

Quelle fehlgeschlagen, versuche /media/podcast.mp3

Fehler bei <source>-Elementen abfangen und Listener entfernen

const video = document.querySelector('video');
const letzteQuelle = video.querySelector('source:last-of-type');

// Bei <source>-Kindern feuert error am <source>-Element, nicht am <video>
const beiFehler = () => {
  video.replaceWith(Object.assign(document.createElement('p'), {
    textContent: 'Video kann in diesem Browser nicht abgespielt werden.'
  }));
  letzteQuelle.removeEventListener('error', beiFehler);
};

letzteQuelle.addEventListener('error', beiFehler);

// Wichtig · Fallstricke

<source>-Falle: Wird die Quelle über <source>-Kindelemente angegeben, feuert error am jeweiligen <source>-Element und nicht am Medienelement; video.error bleibt dabei null. Erst wenn alle Quellen scheitern, wechselt networkState zu NETWORK_NO_SOURCE. Deshalb den Listener auf die letzte <source> setzen oder mit capture: true am Elternelement lauschen.
Das Ereignis steigt nicht auf – Event-Delegation funktioniert nur in der Capture-Phase.
Wird der Handler erst nach dem Setzen von src registriert (z. B. bei HTML-Attributen), kann das Ereignis schon vorbei sein. Dann zusätzlich element.error prüfen oder den Listener vor dem Setzen von src anhängen.
MediaError.message ist browserabhängig und nicht zur Anzeige für Nutzer gedacht. Die Werte darin nicht ungeprüft per innerHTML ausgeben.
Ein abgelehntes play()-Promise (z. B. durch Autoplay-Richtlinien) löst kein error-Ereignis aus – dafür .catch() nutzen.
Browser-Kompatibilität: in allen modernen Browsern verfügbar; MediaError.message wird erst seit etwa 2017/2018 unterstützt.

Siehe auch

GPUDevice: uncapturederror HTMLMediaElement: abort HTMLMediaElement: ended HTMLMediaElement: pause HTMLMediaElement: play