Skip to content

NSError ​

NSError represents an error given by iOS. domain (the error domain) says which part of the system the error came from, such as the file system, location, or Face ID; code is the number within that error domain; message is the system's description.

It appears in two places:

  • When the meaning of the failure is specific to iOS, such as Face ID locked after too many failed attempts: what's thrown, or what a Promise rejects with, is an NSError. name is a category name the runtime gives, such as 'BiometryLockoutError'; when there's no category to give, it's 'NSError', and you look at domain and code.
  • When the meaning of the failure has a name in the web standards, such as no permission: what's thrown is a DOMException, and the system's NSError hangs on its cause. In that case the NSError's name is 'NSError'.

NSError is a global, so err instanceof NSError works. For which errors the runtime throws, see Which error the runtime throws.

Inheritance: Error → NSError

Constructor ​

Can't be created with new; doing so throws TypeError: NSError cannot be constructed; the runtime creates it from a system error. An NSError is only given by the runtime when the system reports an error.

Instance properties ​

Also inherits message (the system's description) and stack (the call stack) from Error. message is in the app's language; see Configuring the app.

PropertyDescription
name read-onlyThe error's category, such as 'BiometryLockoutError'; 'NSError' when there's no category
domain read-onlyThe error domain, such as 'NSCocoaErrorDomain'
code read-onlyThe number within the error domain

Concepts ​

APIs that give an NSError ​

These throw or reject with an NSError directly:

APInamedomain
LAContext: evaluatePolicy() rejecting, and the return value of canEvaluatePolicyError()One of eleven category names, or 'NSError'; see Reasons authentication failed'com.apple.LocalAuthentication'
CLLocationManager location errors'LocationUnknownError' or 'NSError'; see CLLocationError'kCLErrorDomain'
PHPhotoLibrary failing to save an image, except for no permission and a missing usage description'NSError'The domain the system gives
UNUserNotificationCenter errors, except for no permission'NSError'Usually 'UNErrorDomain'
AVCaptureDevice: lockForConfiguration() failing to get the lock'NSError'The domain the system gives
new AVCaptureDeviceInput() failing to open the camera'NSError'An empty string; code is 0
UIWindowScene: requestGeometryUpdateWithPreferences() refused by the system'NSError'The domain the system gives
activityError in the complete event of UIActivityViewController'NSError'The domain the system gives

On the cause of a DOMException: the DOMExceptions given by file access, the keychain, location, saving images, notifications, and web page loading all carry one when the error comes from the system, with name 'NSError'.

Examples ​

Read the system's error code ​

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

async function main() {
  const fs = application.fileSystem;
  try {
    await fs.readText(fs.documents + '/missing.txt');
  } catch (err) {
    const cause = err instanceof Error ? err.cause : undefined;
    if (cause instanceof NSError) {
      console.log(cause.name, cause.domain, cause.code);
      console.log(cause.message);
    }
  }
}
main();

Result (measured):

  • The first line prints NSError NSCocoaErrorDomain 260. Reading a file that doesn't exist rejects with a DOMException whose name is 'NotFoundError', and the system's error hangs on its cause.
  • The second line prints the system's description saying the file doesn't exist.

Corresponding iOS API ​

ObjCJS
error.domainerr.domain
error.codeerr.code
error.localizedDescriptionerr.message
error.userInfoNot provided in JS
A method's NSError ** out-parameter, a callback's NSError * parameterThe error a method throws, or the value a Promise rejects with

See also ​

  • DOMException: errors whose meaning has a name in the web standards; the system's NSError hangs on its cause
  • LAContext: every reason Face ID authentication can fail
  • CLLocationError: the errors location gives