Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Globals and Console

The DOMException class

Reference for DOMException in Node.js: the standard web error type used by AbortSignal, structuredClone and btoa, with names, legacy codes and how to check them.

DOMException is the standard error type of the web platform. Despite the name it has nothing to do with the DOM; it is simply the class that web-style APIs use to report failures, and Node.js uses it for the same APIs: AbortSignal (AbortError, TimeoutError), structuredClone() (DataCloneError), btoa() and atob() (InvalidCharacterError).

You rarely construct one yourself, but you often receive one in a catch block. The reliable way to recognise the failure is by its name.

NODE
const error = new DOMException('Operation was cancelled', 'AbortError');

Try it

Node.js Reading a DOMException

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js DOMExceptions thrown by built-in APIs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
new DOMException([message[, nameOrOptions]])
Name Description
message Human-readable description. Defaults to an empty string.
nameOrOptions A name string, or an object { name, cause }. The name defaults to 'Error'.

Properties: name, message, code (legacy number, 0 if the name has none), stack, and cause when supplied.

Static constants: DOMException.INDEX_SIZE_ERR (1), SYNTAX_ERR (12), NOT_FOUND_ERR (8), ABORT_ERR (20), TIMEOUT_ERR (23), DATA_CLONE_ERR (25), and the rest of the legacy list.

Usage notes

  • Check name, not the message. Messages vary between runtimes and versions; names such as AbortError, TimeoutError, DataCloneError, InvalidCharacterError, NotFoundError, NotSupportedError, SyntaxError and InvalidStateError are standardized.
  • Names map to legacy codes only for the old built-in list. A custom name gives code 0.
  • It is an Error. instanceof Error is true and it has a stack, so it works with ordinary error handling. Its prototype chain is different from other errors in older runtimes; do not depend on constructor.name.
  • Cross-realm checks: instanceof DOMException can fail for exceptions that come from another realm (a worker, a vm context). The name check does not.
  • Throw it for web-like APIs: if you write a cancellable function, rejecting with the signal.reason (via signal.throwIfAborted()) keeps behavior consistent with the built-ins.
  • For application errors, a custom Error subclass with a code property is more idiomatic in Node.js; reserve DOMException for web-compatible behavior.
  • Serialization: DOMException objects can be cloned with structuredClone() and posted between threads, keeping name and message.
  • Global since Node.js 17.