MediaError.message — Eigenschaft · JavaScript-Referenz

Signatur

MediaError.message

Beschreibung

Die schreibgeschützte Eigenschaft MediaError.message liefert einen für Menschen lesbaren Text mit genaueren Angaben zu einem Fehler, der beim Laden oder Abspielen eines <audio>- oder <video>-Elements aufgetreten ist. Das MediaError-Objekt erreicht man über die Eigenschaft HTMLMediaElement.error, meist im Handler des error-Events.

Die Eigenschaft code ordnet den Fehler nur grob in eine von vier Kategorien ein (MEDIA_ERR_ABORTED, MEDIA_ERR_NETWORK, MEDIA_ERR_DECODE, MEDIA_ERR_SRC_NOT_SUPPORTED). message ergänzt das um Details vom Browser, etwa welcher Decoder versagt hat oder welcher HTTP-Status gekommen ist. Gibt es keine Details, ist der Wert ein leerer String "".

Nutzen Sie message für Protokollierung, Fehlerberichte und Fehlersuche, nicht für Programmlogik. Inhalt und Formulierung sind nicht standardisiert und unterscheiden sich je nach Browser und Version. Verzweigungen im Code sollten immer auf code beruhen.

Rückgabewert

Typ

string

Beschreibung

Browserspezifischer Diagnosetext zum Fehler oder "", wenn keine Details vorliegen.

Beispiele

Fehlermeldung im error-Event auslesen

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

video.addEventListener('error', () => {
  const { code, message } = video.error;
  console.error(`Medienfehler (Code ${code}): ${message || 'keine Details verfügbar'}`);
});

video.src = '/videos/nicht-vorhanden.mp4';

Medienfehler (Code 4): MEDIA_ELEMENT_ERROR: Format error // Text je nach Browser verschieden

Nutzerfreundliche Meldung über code, Details über message protokollieren

const texte = {
  [MediaError.MEDIA_ERR_ABORTED]: 'Wiedergabe wurde abgebrochen.',
  [MediaError.MEDIA_ERR_NETWORK]: 'Netzwerkfehler beim Laden.',
  [MediaError.MEDIA_ERR_DECODE]: 'Die Datei ist beschädigt.',
  [MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED]: 'Format wird nicht unterstützt.'
};

const audio = new Audio('/audio/podcast.xyz');

audio.onerror = () => {
  const err = audio.error;
  // Anzeige für Nutzer: stabil über code
  document.querySelector('#status').textContent = texte[err.code] ?? 'Unbekannter Fehler.';
  // Technische Details nur ins Log
  console.debug('Diagnose:', err.message);
};

Diagnose: DEMUXER_ERROR_COULD_NOT_OPEN // Beispiel aus Chromium

Fehlerbericht an den Server senden

const reportMediaError = async (media) => {
  const { code, message } = media.error ?? {};
  await fetch('/api/fehlerbericht', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      quelle: media.currentSrc,
      code,
      message: message ?? '',
      userAgent: navigator.userAgent
    })
  });
};

document.querySelector('video')
  .addEventListener('error', (e) => reportMediaError(e.target));

// Wichtig · Fallstricke

Nicht standardisierter Inhalt: Der Text unterscheidet sich zwischen Chrome, Firefox und Safari und kann sich mit jeder Version ändern. Prüfen Sie nie per String-Vergleich auf message, sondern verwenden Sie code.
Leerer String möglich: Oft liefert der Browser keine Details, etwa bei MEDIA_ERR_ABORTED. Planen Sie dafür immer einen Ersatztext ein.
error kann null sein: HTMLMediaElement.error ist null, solange kein Fehler aufgetreten ist. Greifen Sie deshalb mit optionaler Verkettung zu: media.error?.message.
Fehler an <source>-Elementen: Scheitert eine einzelne Quelle, wird das error-Event am <source>-Element ausgelöst und nicht am Medienelement. In diesem Fall bleibt media.error womöglich null.
Datenschutz: Die Meldung kann URLs oder Serverantworten enthalten. Zeigen Sie sie Endnutzern nicht ungefiltert an und prüfen Sie Fehlerberichte auf sensible Daten.
Kompatibilität: Wird in allen aktuellen Browsern unterstützt (Chrome 59+, Firefox 52+, Safari 15+). In älteren Browsern ist der Wert undefined.

Siehe auch

BarProp.visible ErrorEvent.message MediaError.code GPUError.message DOMException.message