new DOMException() — Methode · JavaScript-Referenz

Signatur

new DOMException(message, name)

Beschreibung

Mit dem Konstruktor DOMException() erzeugt man Fehlerobjekte, die genauso aussehen wie die Ausnahmen, die Web-APIs selbst werfen. Das ist praktisch, wenn eigene Bibliotheken oder Polyfills sich wie native Browser-APIs verhalten sollen. Ein typischer Fall ist ein AbortError bei abbrechbaren Operationen mit AbortSignal.

Der Parameter name bestimmt die Fehlerart. Ist er einer der standardisierten Namen (z. B. "NotFoundError", "InvalidStateError", "AbortError", "TimeoutError"), setzt der Browser die veraltete Eigenschaft code automatisch auf den passenden numerischen Legacy-Code. Bei anderen Namen ist code immer 0.

In modernen Umgebungen erbt DOMException von Error. instanceof Error ist also true, und je nach Engine gibt es auch einen stack. Aufrufender Code sollte Fehler über err.name unterscheiden, nicht über err.code oder den Text der Meldung.

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Lesbare Beschreibung des Fehlers. Sie steht danach in `exception.message`.
$name	string	"Error"	Name des Fehlers, z. B. `"AbortError"` oder `"NotAllowedError"`. Steht in `exception.name` und legt bei Standardnamen auch `exception.code` fest.

Rückgabewert

Typ

DOMException

Beschreibung

Ein neues DOMException-Objekt mit den Eigenschaften message und name sowie code (veraltet).

Beispiele

Einfache Instanziierung und Eigenschaften

const err = new DOMException('Element wurde nicht gefunden', 'NotFoundError');

console.log(err.name);    // Fehlername
console.log(err.message); // Meldung
console.log(err.code);    // Legacy-Code für NotFoundError
console.log(err instanceof Error);

NotFoundError Element wurde nicht gefunden 8 true

Abbrechbare Verzögerung mit AbortError

const delay = (ms, { signal } = {}) => new Promise((resolve, reject) => {
  if (signal?.aborted) {
    return reject(new DOMException('Vorgang abgebrochen', 'AbortError'));
  }
  const id = setTimeout(resolve, ms);
  signal?.addEventListener('abort', () => {
    clearTimeout(id);
    reject(new DOMException('Vorgang abgebrochen', 'AbortError'));
  }, { once: true });
});

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

try {
  await delay(1000, { signal: controller.signal });
} catch (err) {
  if (err.name === 'AbortError') {
    console.log('Abgebrochen:', err.message);
  } else {
    throw err;
  }
}

Abgebrochen: Vorgang abgebrochen

Eigener Timeout-Fehler für fetch

const fetchWithTimeout = async (url, ms) => {
  const controller = new AbortController();
  const timer = setTimeout(
    () => controller.abort(new DOMException(`Timeout nach ${ms} ms`, 'TimeoutError')),
    ms
  );
  try {
    return await fetch(url, { signal: controller.signal });
  } finally {
    clearTimeout(timer);
  }
};

try {
  await fetchWithTimeout('https://example.com/langsam', 50);
} catch (err) {
  console.log(err.name, '-', err.message);
}

TimeoutError - Timeout nach 50 ms

Nicht standardisierter Name ergibt code 0

const custom = new DOMException('Kontingent überschritten', 'MeinFehler');
console.log(custom.name, custom.code);

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

MeinFehler 0 "" Error

// Wichtig · Fallstricke

Nach name unterscheiden: code und die Konstanten wie DOMException.ABORT_ERR sind veraltet. Neue Fehlerarten bekommen keinen numerischen Code mehr.
Reihenfolge der Argumente: Zuerst kommt message, dann name. Das ist umgekehrt zu dem, was viele intuitiv erwarten. new DOMException('AbortError') erzeugt einen Fehler mit dem Namen "Error".
Nur mit new: Ohne new wirft der Aufruf einen TypeError.
Kompatibilität: Der Konstruktor funktioniert in allen modernen Browsern, nicht aber im Internet Explorer. In Node.js ist DOMException ab Version 17 global verfügbar, davor nur über Umwege.
Vererbung: Dass DOMException von Error erbt, ist erst seit neueren Versionen der Spezifikation garantiert. Ob es einen stack gibt, hängt von der Engine ab.
Das Objekt lässt sich mit structuredClone() kopieren und per postMessage() übertragen. Dabei bleiben name und message erhalten.

Siehe auch

DOMException Error AbortSignal.timeout() throw try...catch new CSSMatrixComponent()