HTMLMediaElement.error — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLMediaElement.error

Beschreibung

Die schreibgeschützte Eigenschaft error von HTMLMediaElement (also <audio> und <video>) enthält ein MediaError-Objekt für den zuletzt aufgetretenen Fehler beim Laden oder Abspielen der Medienquelle. Solange kein Fehler aufgetreten ist, hat sie den Wert null.

Das MediaError-Objekt hat zwei Eigenschaften: code (eine Zahl von 1 bis 4) und message (ein Text mit Details, abhängig vom Browser, oft leer). Die Codes haben folgende Bedeutung:

1 – MEDIA_ERR_ABORTED: Der Nutzer oder das Skript hat den Ladevorgang abgebrochen.
2 – MEDIA_ERR_NETWORK: Netzwerkfehler während des Ladens.
3 – MEDIA_ERR_DECODE: Die Datei konnte nicht dekodiert werden (z. B. beschädigt).
4 – MEDIA_ERR_SRC_NOT_SUPPORTED: Die Quelle bzw. das Format wird nicht unterstützt oder ist nicht erreichbar.

Typischerweise liest man error im Handler des error-Events aus, um Nutzern eine verständliche Fehlermeldung anzuzeigen, auf eine andere Quelle auszuweichen oder den Fehler an ein Monitoring zu melden. Wird eine neue Quelle geladen (z. B. über load() oder eine Änderung von src), wird error wieder auf null zurückgesetzt.

Rückgabewert

Typ

MediaError | null

Beschreibung

Ein MediaError-Objekt mit code und message oder null, wenn kein Fehler aufgetreten ist.

Beispiele

Fehlercode im error-Event auswerten

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

const fehlertexte = {
  [MediaError.MEDIA_ERR_ABORTED]: 'Wiedergabe wurde abgebrochen.',
  [MediaError.MEDIA_ERR_NETWORK]: 'Netzwerkfehler beim Laden des Videos.',
  [MediaError.MEDIA_ERR_DECODE]: 'Das Video ist beschädigt oder nicht dekodierbar.',
  [MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED]: 'Format nicht unterstützt oder Datei nicht gefunden.'
};

video.addEventListener('error', () => {
  const { code, message } = video.error;
  console.error(`Fehler ${code}: ${fehlertexte[code] ?? 'Unbekannter Fehler'}`, message);
});

video.src = '/videos/gibt-es-nicht.mp4';

Fehler 4: Format nicht unterstützt oder Datei nicht gefunden.

Auf eine Ersatzquelle ausweichen

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

const onError = () => {
  console.warn(`Quelle ${audio.src} fehlgeschlagen (Code ${audio.error.code})`);
  index += 1;
  if (index < quellen.length) {
    audio.src = quellen[index]; // error wird dadurch wieder null
  } else {
    audio.removeEventListener('error', onError);
    console.error('Keine abspielbare Quelle gefunden.');
  }
};

audio.addEventListener('error', onError);
audio.src = quellen[index];

Zustand vor dem Abspielen prüfen

const player = document.querySelector('#player');

const sicherAbspielen = async () => {
  if (player.error) {
    console.log('Letzter Fehler:', player.error.code);
    player.load(); // setzt error zurück und lädt neu
  }
  try {
    await player.play();
  } catch (err) {
    // z. B. NotAllowedError durch Autoplay-Richtlinie – kein MediaError!
    console.log('play() abgelehnt:', err.name);
  }
};

document.querySelector('#play').addEventListener('click', sicherAbspielen);

// Wichtig · Fallstricke

Nur lesbar: error kann nicht gesetzt werden. Zurückgesetzt wird es nur durch Laden einer neuen Quelle (load(), neues src).
Fehler von <source>-Kindern: Scheitert eine einzelne <source>, feuert das error-Event am <source>-Element, nicht am Medienelement, und video.error bleibt null. Erst wenn alle Quellen scheitern, wird networkState auf NETWORK_NO_SOURCE gesetzt. Um Fehler einzelner Quellen mitzubekommen, auf das letzte <source> hören oder mit addEventListener('error', fn, true) in der Capture-Phase abfangen.
message ist nicht einheitlich: Inhalt und Detailgrad sind je nach Browser unterschiedlich und oft leer. Nicht zum Parsen verwenden, nur zum Protokollieren.
Abgelehnte play()-Promises (z. B. NotAllowedError durch Autoplay-Richtlinien) erzeugen keinen MediaError. Sie müssen per try/catch behandelt werden.
Code 4 tritt auch bei 404-Antworten oder CORS-Problemen auf, weil der Browser diese aus Sicherheitsgründen nicht genauer unterscheidet.
Kompatibilität: in allen modernen Browsern unterstützt. MediaError.message gibt es erst seit etwa 2017 (Chrome 59, Firefox 52, Safari 15).

Siehe auch

HTMLMediaElement.controls HTMLMediaElement.ended HTMLMediaElement.loop HTMLMediaElement.src HTMLMediaElement.muted