DOMException — Schnittstelle · JavaScript-Referenz

Signatur

interface DOMException extends Error

Beschreibung

DOMException ist der Standard-Fehlertyp der Web-Plattform. Schlägt eine Web-API fehl, etwa ein abgebrochener fetch()-Aufruf, ein ungültiger CSS-Selektor in querySelector(), ein verweigerter Zugriff auf Kamera oder Zwischenablage oder ein IndexedDB-Konflikt, dann wirft sie (oder lehnt ein Promise ab mit) einer Instanz von DOMException.

Wichtig ist vor allem die Eigenschaft name. Sie gibt die Fehlerart als Zeichenkette an, z. B. "AbortError", "NotFoundError", "SyntaxError", "NotAllowedError", "QuotaExceededError", "InvalidStateError", "TimeoutError" oder "DataCloneError". Dazu kommen message (lesbare Beschreibung) und die veraltete numerische Eigenschaft code samt Konstanten wie DOMException.NOT_FOUND_ERR.

Seit einiger Zeit ist DOMException eine echte Unterklasse von Error. Daher funktionieren instanceof Error und stack in modernen Umgebungen. Mit dem Konstruktor new DOMException(message, name) kannst du auch in eigenem Code Fehler werfen, die sich wie native Web-API-Fehler verhalten. Das ist z. B. sinnvoll, wenn du eine eigene abbrechbare Funktion mit AbortSignal baust.

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Lesbare Fehlerbeschreibung. Sie landet in der Eigenschaft `message`.
$name	string	"Error"	Fehlername, z. B. `"AbortError"` oder `"NotFoundError"`. Ist der Name ein bekannter Legacy-Name, wird `code` passend gesetzt, sonst ist `code` gleich `0`.

Rückgabewert

Typ

DOMException

Beschreibung

Konstruktor new DOMException(message, name): eine neue Instanz mit den nur lesbaren Eigenschaften name, message und code.

Beispiele

Abgebrochenen fetch-Aufruf von echten Fehlern unterscheiden

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

try {
  const res = await fetch('https://httpbin.org/delay/3', { signal: controller.signal });
  console.log(await res.json());
} catch (err) {
  if (err instanceof DOMException && err.name === 'AbortError') {
    console.log('Anfrage wurde abgebrochen');
  } else {
    throw err; // echter Netzwerkfehler (TypeError) o. Ä.
  }
}

Anfrage wurde abgebrochen

Ungültigen CSS-Selektor abfangen

const findeSicher = (selektor) => {
  try {
    return document.querySelector(selektor);
  } catch (err) {
    if (err.name === 'SyntaxError') {
      console.warn(`Ungültiger Selektor: ${selektor}`);
      return null;
    }
    throw err;
  }
};

findeSicher('div[');

Ungültiger Selektor: div[

Eigene DOMException in einer abbrechbaren Funktion werfen

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

const ac = new AbortController();
warte(5000, { signal: ac.signal }).catch((e) => console.log(e.name, e.message, e.code));
ac.abort();

AbortError Warten abgebrochen 20

Berechtigungsfehler bei der Zwischenablage behandeln

const kopiere = async (text) => {
  try {
    await navigator.clipboard.writeText(text);
    console.log('Kopiert');
  } catch (err) {
    switch (err.name) {
      case 'NotAllowedError':
        console.log('Zugriff verweigert – Nutzergeste oder Berechtigung fehlt');
        break;
      default:
        console.error('Unerwarteter Fehler:', err);
    }
  }
};

kopiere('Hallo Welt');

Kopiert

// Wichtig · Fallstricke

Prüfe name, nicht code: code und die Konstanten wie DOMException.ABORT_ERR gelten als veraltet. Neuere Fehlerarten wie NotAllowedError oder NotReadableError haben code === 0.
Nicht jeder Web-API-Fehler ist eine DOMException: fetch() lehnt bei Netzwerkfehlern mit einem TypeError ab. Nur beim Abbruch kommt eine DOMException mit Namen AbortError. Vergleiche am besten instanceof DOMException und name zusammen.
AbortSignal.timeout() bricht mit einer DOMException namens TimeoutError ab und nicht mit AbortError. Behandle beide Fälle.
signal.reason kann ein beliebiger Wert sein, wenn abort(reason) mit eigenem Grund aufgerufen wurde. Verlass dich also nicht blind auf eine DOMException.
Kompatibilität: Der Konstruktor und die Vererbung von Error (inkl. stack) gibt es in allen aktuellen Browsern. In sehr alten Browsern (IE) lässt sich DOMException nicht instanziieren. In Node.js ist DOMException ab Version 17 global verfügbar.
DOMException ist serialisierbar. Du kannst sie per postMessage() oder structuredClone() übertragen, dabei bleiben name und message erhalten.

Siehe auch

Error try...catch Location Selection CDATASection