Skip to content

DOMException ​

DOMException represents an error classified by name. name says which kind of error it is, using names from the web standards, such as 'AbortError' (canceled), 'NotFoundError' (not found), and 'NotAllowedError' (no permission); message is a one-sentence description; code is the legacy numeric code the web standards give that name.

When a runtime API fails and the meaning of the failure has a name in the web standards, what's thrown, or what a Promise rejects with, is a DOMException. When the error comes from iOS, the system's original error hangs on cause as an NSError; see The original system error.

It's in the core, so it needs no package. App code can also create a DOMException itself or subclass it.

Inheritance: Error → DOMException

Constructor ​

DOMException()

Creates an error with a description and a name.

Static properties ​

Error code constants

DOMException.ABORT_ERR and 24 other constants, each a legacy numeric code. Instances have the same 25 constants.

Instance properties ​

Also inherits stack (the call stack) and cause from Error. When an error the runtime gives comes from iOS, cause is the system's NSError.

PropertyDescription
name read-onlyThe error's category, such as 'AbortError'
message read-onlyA one-sentence description
code read-onlyThe legacy numeric code for the name; 0 for names without one

Concepts ​

Which error the runtime throws ​

When a runtime API fails, what's thrown, or what a Promise rejects with, is one of these four:

SituationThrownExamples
An argument has the wrong typeTypeErrorA value other than an AVCaptureDevice where one is required; a network request that couldn't complete (fetch() rejects with TypeError, as the web standard says)
An argument has the right type but is out of the allowed rangeRangeErrorA camera zoom factor beyond what the camera can do
The meaning of the failure has a name in the web standardsDOMExceptionA canceled request, a missing file, no permission
The meaning of the failure is specific to iOSNSErrorFace ID locked after too many failed attempts; no location available at this moment

To tell what went wrong, check name. All four are instances of Error, and name is always a string: for TypeError and RangeError it's the class name, and for DOMException and NSError it's the category name. To tell the classes apart, use instanceof DOMException and instanceof NSError.

Names the runtime gives ​

The DOMExceptions the runtime gives use only these names:

namecodeWhen it occurs
'AbortError'20A request canceled by an AbortController; the default abort reason of an AbortSignal; a one-time location request on CLLocationManager canceled; a webContents load stopped
'TimeoutError'23The abort reason when AbortSignal.timeout() expires; runBackgroundTask() running out of time
'NotFoundError'8application.fileSystem can't find a file or directory
'NotAllowedError'0No permission: file access, the keychain, location, saving images, notifications
'InvalidStateError'11Can't be done in the current state: sending on a WebSocket that isn't connected, calling waitUntil() after a PushEvent has been dispatched, changing an AVCaptureDevice setting without the lock, and a few cases in location and saving images
'NetworkError'19A network problem while locating; a web page failing to load; a network error during a WebSocket send or ping()
'InvalidModificationError'13File access: a file already exists at the destination; keychain: an item conflict
'QuotaExceededError'22Device storage is full; crypto.getRandomValues() asked for more than 65536 bytes at once
'NoModificationAllowedError'7File access: the storage is read-only
'TypeMismatchError'17File access: an invalid file name; keychain: an invalid argument; crypto.getRandomValues() given a float array or a DataView
'SecurityError'18Keychain: the app lacks the entitlement needed to access the keychain
'OperationError'0File access and keychain failures with no more specific name; the system random source failing
'InvalidCharacterError'5atob() and btoa() meeting a character they can't handle
'DataCloneError'25structuredClone() meeting a value it can't copy

Exactly when each name occurs, and the text of each message, is on each API's page.

The original system error ​

When the error comes from iOS, the DOMException's cause is the error the system gave, an NSError. Its domain is the error domain, its code is the number within that domain, its message is the system's description, and its name is 'NSError'.

name tells you what category of error occurred, and in most cases it's all you need. To tell apart different causes under the same name, or to log the system's error code, read cause.

Errors the runtime determines on its own have no cause, such as a request canceled by an AbortController or a send on a WebSocket that isn't connected. Check that cause is an NSError before reading it.

Examples ​

Tell apart errors when reading a file ​

js
/// <reference types="@nacrejs/types" />

async function main() {
  const fs = application.fileSystem;
  try {
    await fs.readText(fs.documents + '/missing.txt');
  } catch (err) {
    if (err instanceof DOMException && err.name === 'NotFoundError') {
      console.log('File not found', err.code);
      if (err.cause instanceof NSError) {
        console.log(err.cause.domain, err.cause.code);
      }
    } else {
      throw err;
    }
  }
}
main();

Result (measured):

  • The first line prints File not found 8.
  • The second line prints NSCocoaErrorDomain 260: the system's error domain and error code.

Give your own abort reason ​

js
const controller = new AbortController();
controller.abort(new DOMException('The user left the page', 'AbortError'));
const reason = controller.signal.reason;
console.log(String(reason), reason instanceof DOMException);

Result: Prints AbortError: The user left the page true.

Differences from the web ​

  • Passing null as the constructor's message or name gives an empty string. On the web it gives the string 'null'.
  • Errors the runtime gives carry cause when they come from iOS.

See also ​

  • NSError: the system error on cause, and errors whose meaning is specific to iOS
  • AbortSignal: the abort reason is 'AbortError' by default and 'TimeoutError' on timeout
  • application.fileSystem: every error file access can give