DOMError — Schnittstelle · JavaScript-Referenz

Signatur

interface DOMError

Beschreibung

DOMError beschreibt ein einfaches Fehlerobjekt mit zwei schreibgeschützten Eigenschaften: name ist der Fehlertyp als Zeichenkette (z. B. "NotFoundError", "AbortError" oder "QuotaExceededError"), message ist eine lesbare Beschreibung für Menschen. Das Objekt wird nicht geworfen, sondern steht als Wert in einer Fehler-Eigenschaft einer anderen API.

Frühere Fassungen verschiedener Spezifikationen nutzten DOMError, etwa IDBRequest.error und IDBTransaction.error (IndexedDB), FileReader.error und einzelne WebRTC- und Media-APIs. Diese Stellen liefern heute alle ein DOMException-Objekt. Das hat dieselben Eigenschaften name und message, erbt aber zusätzlich von Error.

Neuen Code nicht mit DOMError schreiben. Nutzen Sie DOMException und werten Sie Fehler über die Eigenschaft name aus. Das funktioniert mit beiden Typen. Die Schnittstelle ist vor allem wichtig, wenn Sie alten Code lesen oder auf neue APIs umstellen.

Parameter

Name	Typ	Default	Beschreibung
$name	string	"Error"	Nur beim alten, nicht standardisierten Konstruktor `new DOMError(name, message)`: Name des Fehlertyps. Als Eigenschaft ist `name` schreibgeschützt.
$message	string	""	Nur beim alten Konstruktor: lesbare Fehlerbeschreibung. Als Eigenschaft ist `message` schreibgeschützt.

Rückgabewert

Typ

DOMError

Beschreibung

Ein Fehlerobjekt mit den schreibgeschützten Eigenschaften name (string) und message (string). Es erbt nicht von Error und hat daher keinen Stacktrace.

Beispiele

Prüfen, ob die Schnittstelle noch vorhanden ist

// DOMError gibt es nicht mehr in allen Umgebungen
const hatDomError = typeof globalThis.DOMError === 'function';
const hatDomException = typeof globalThis.DOMException === 'function';

console.log(`DOMError: ${hatDomError}, DOMException: ${hatDomException}`);

DOMError: false, DOMException: true (je nach Browser/Umgebung)

Fehler aus IndexedDB unabhängig vom Typ auswerten

// request.error war früher ein DOMError, heute ein DOMException.
// Die Auswertung über .name funktioniert mit beiden.
const request = indexedDB.open('meine-db', 1);

request.onerror = () => {
  const { name, message } = request.error;
  switch (name) {
    case 'VersionError':
      console.warn('Die Datenbank hat bereits eine neuere Version.');
      break;
    case 'QuotaExceededError':
      console.warn('Der Speicher ist voll.');
      break;
    default:
      console.error(`${name}: ${message}`);
  }
};

request.onsuccess = () => console.log('DB geöffnet:', request.result.name);

DB geöffnet: meine-db

Umstellung: DOMException statt DOMError erzeugen

// Alt (veraltet, nicht standardisiert):
// const fehler = new DOMError('NotFoundError', 'Datei fehlt');

// Neu:
const fehler = new DOMException('Datei fehlt', 'NotFoundError');

console.log(fehler.name);              // Fehlertyp
console.log(fehler.message);           // Meldung
console.log(fehler instanceof Error);  // true – im Gegensatz zu DOMError

// DOMException kann geworfen und mit try/catch gefangen werden
try {
  throw fehler;
} catch (e) {
  if (e.name === 'NotFoundError') console.log('Behandelt:', e.message);
}

NotFoundError Datei fehlt true Behandelt: Datei fehlt

// Wichtig · Fallstricke

Veraltet: DOMError wurde aus dem DOM-Standard entfernt. Manche Browser bieten die Schnittstelle nicht mehr an, bei anderen gibt es sie nur noch aus Kompatibilitätsgründen. Verlassen Sie sich nicht auf typeof DOMError oder instanceof DOMError.
Die Argumente sind vertauscht: Beim alten Konstruktor steht name vorn: new DOMError(name, message). Bei new DOMException(message, name) steht die Meldung vorn. Achten Sie beim Umstellen auf die Reihenfolge.
DOMError erbt nicht von Error. Prüfungen wie err instanceof Error schlagen deshalb fehl, und es gibt keinen stack. Werten Sie Fehler robust über err.name aus.
Die alten numerischen Fehlercodes (code) gab es nur bei DOMException, nicht bei DOMError. Auch dort gelten sie als veraltet.

Siehe auch

Error try...catch GPUError RTCError DOMParser