DOMException.message — Eigenschaft · JavaScript-Referenz

Signatur

get DOMException.prototype.message

Beschreibung

Die schreibgeschützte Eigenschaft message einer DOMException enthält eine Zeichenkette mit einer Beschreibung des Fehlers. Sie ergänzt die Eigenschaft name, die den Fehlertyp maschinenlesbar angibt (z. B. "AbortError", "NotAllowedError" oder "QuotaExceededError").

Wird eine DOMException vom Browser ausgelöst, legt die jeweilige Engine den Text fest. Er ist daher nicht standardisiert und unterscheidet sich zwischen Chrome, Firefox und Safari sowie zwischen Versionen. Erzeugt man die Ausnahme selbst mit new DOMException(message, name), entspricht message genau dem ersten Argument (Standard: leere Zeichenkette).

In der Praxis eignet sich message für Logs, Debugging-Ausgaben und Fehlerberichte. Für Programmlogik, also für die Frage „welcher Fehler ist aufgetreten?“, sollte man immer name prüfen und nicht den Text von message.

Rückgabewert

Typ

string

Beschreibung

Die Fehlerbeschreibung. Bei selbst erzeugten Ausnahmen ist das der an den Konstruktor übergebene Text, sonst ein vom Browser festgelegter Text. Wurde nichts übergeben, ist es "".

Beispiele

Eigene DOMException erzeugen und message auslesen

const err = new DOMException('Upload wurde vom Benutzer abgebrochen', 'AbortError');

console.log(err.name);    // Fehlertyp
console.log(err.message); // Beschreibung
console.log(String(err)); // name + message kombiniert

AbortError Upload wurde vom Benutzer abgebrochen AbortError: Upload wurde vom Benutzer abgebrochen

Abgebrochenen fetch-Aufruf protokollieren

const controller = new AbortController();
setTimeout(() => controller.abort(), 10);

try {
  await fetch('https://example.com/grosse-datei', { signal: controller.signal });
} catch (err) {
  if (err instanceof DOMException && err.name === 'AbortError') {
    // Logik über name, message nur fürs Logging
    console.warn(`Anfrage abgebrochen: ${err.message}`);
  } else {
    throw err;
  }
}

Anfrage abgebrochen: The operation was aborted. (Text je nach Browser verschieden)

Fehler bei ungültigem CSS-Selektor

try {
  document.querySelector('div[');
} catch (err) {
  console.log(err.name);
  console.log(err.message);
}

SyntaxError Failed to execute 'querySelector' on 'Document': 'div[' is not a valid selector. (Chrome)

Standardwert ohne Nachricht

const leer = new DOMException();
console.log(JSON.stringify(leer.message));
console.log(leer.name);

"" Error

// Wichtig · Fallstricke

Text nicht vergleichen: Der Inhalt von message hängt vom Browser ab und kann lokalisiert sein oder sich ändern. Für Fallunterscheidungen immer err.name verwenden.
Schreibgeschützt: message ist ein Getter auf dem Prototyp. Eine Zuweisung wie err.message = '...' ändert den Wert nicht und löst im Strict Mode einen TypeError aus.
Keine Nutzereingaben ungeprüft anzeigen: Meldungen können Teile von Eingaben enthalten, etwa Selektoren. Beim Ausgeben im DOM textContent statt innerHTML verwenden, damit kein XSS entsteht.
Seit neueren Spezifikationen erbt DOMException von Error.prototype. Daher funktionieren err instanceof Error und toString() in allen modernen Browsern. In Node.js ist DOMException ab Version 17 global verfügbar.

Siehe auch

DOMException DOMException.name Error.prototype.message DeviceOrientationEvent.gamma MediaError.message