@ohos.app.ability.errorManager (ErrorManager)

The ErrorManager module provides APIs for registering and unregistering error observers.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { errorManager } from '@kit.AbilityKit';

errorManager.on('error')

NOTE

The errormanager.on API is registered only in the main thread. Currently, exceptions in child threads (such as TaskPool threads) cannot be captured.

The application does not exit during the use of errormanager.on. You are advised to add the synchronous exit operation after the callback function is executed.

on(type: 'error', observer: ErrorObserver): number

Registers an error observer. After the registration, JS crashes generated by the application can be captured. When the application breaks down, the process does not exit.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'error'.
observer	ErrorObserver	Yes	Digital code of the observer.

Return value

Type	Description
number	Index of the observer.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16000003	The specified ID does not exist.

Example

import { errorManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let observer: errorManager.ErrorObserver = {
  onUnhandledException(errorMsg) {
    console.log('onUnhandledException, errorMsg: ', errorMsg);
  },
  onException(errorObj) {
    console.log('onException, name: ', errorObj.name);
    console.log('onException, message: ', errorObj.message);
    if (typeof(errorObj.stack) === 'string') {
      console.log('onException, stack: ', errorObj.stack);
    }
  }
};
let observerId = -1;

try {
  observerId = errorManager.on('error', observer);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`error: ${code}, ${message}`);
}

errorManager.off('error')

off(type: 'error', observerId: number, callback: AsyncCallback<void>): void

Unregisters an error observer. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'error'.
observerId	number	Yes	Index of the observer returned by on().
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16000003	The specified ID does not exist.

Example

import { errorManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let observerId = 100;

function unregisterErrorObserverCallback(err: BusinessError) {
  if (err) {
    console.error('------------ unregisterErrorObserverCallback ------------', err);
  }
}

try {
  errorManager.off('error', observerId, unregisterErrorObserverCallback);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`error: ${code}, ${message}`);
}

errorManager.off('error')

off(type: 'error', observerId: number): Promise<void>

Unregisters an error observer. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'error'.
observerId	number	Yes	Index of the observer returned by on().

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16000003	The specified ID does not exist.

Example

import { errorManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let observerId = 100;

try {
  errorManager.off('error', observerId)
    .then((data) => {
      console.log('----------- unregisterErrorObserver success ----------', data);
    })
    .catch((err: BusinessError) => {
      console.error('----------- unregisterErrorObserver fail ----------', err);
    });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`error: ${code}, ${message}`);
}

errorManager.on('loopObserver')¹²⁺

on(type: 'loopObserver', timeout: number, observer: LoopObserver): void

Registers an observer for the message processing duration of the main thread. After the registration, the execution time of a message processed by the main thread of the application can be captured.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'loopObserver', indicating an observer for the message processing duration of the main thread.
timeout	number	Yes	Event execution threshold, in milliseconds. The value must be greater than 0.
observer	LoopObserver	Yes	Observer to register.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.

Example

import { errorManager } from '@kit.AbilityKit';

let observer: errorManager.LoopObserver = {
  onLoopTimeOut(timeout: number) {
    console.log('Duration timeout: ' + timeout);
  }
};

errorManager.on("loopObserver", 1, observer);

errorManager.on('unhandledRejection')¹²⁺

on(type: 'unhandledRejection', observer: UnhandledRejectionObserver): void

Registers an observer for the promise rejection. After the registration, a rejected promise that is not captured in the current thread of the application can be captured.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'unhandledRejection', indicating an observer for the promise rejection.
observer	UnhandledRejectionObserver	Yes	Observer to register.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16200001	If the caller is invalid.

Example

import { errorManager } from '@kit.AbilityKit';

let observer: errorManager.UnhandledRejectionObserver = (reason: Error, promise: Promise<void>) => {
  if (promise === promise1) {
    console.log("promise1 is rejected");
  }
  console.log("reason.name: ", reason.name);
  console.log("reason.message: ", reason.message);
  if (reason.stack) {
    console.log("reason.stack: ", reason.stack);
  }
};

errorManager.on("unhandledRejection", observer);

let promise1 = new Promise<void>(() => {}).then(() => {
  throw new Error("uncaught error");
});

errorManager.off('loopObserver')¹²⁺

off(type: 'loopObserver', observer?: LoopObserver): void

Unregisters an observer for the message processing duration of the main thread.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'loopObserver', indicating an observer for the message processing duration of the main thread.
observer	LoopObserver	No	Observer to unregister.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.

Example

import { errorManager } from '@kit.AbilityKit';

errorManager.off("loopObserver");

errorManager.off('unhandledRejection')¹²⁺

off(type: 'unhandledRejection', observer?: UnhandledRejectionObserver): void

Unregisters an observer for the promise rejection.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'unhandledRejection', indicating an observer for the promise rejection.
observer	UnhandledRejectionObserver	No	Observer to unregister.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16200001	If the caller is invalid.
16300004	If the observer does not exist.

For details about the error codes, see Ability Error Codes.

Example

import { errorManager } from '@kit.AbilityKit';

let observer: errorManager.UnhandledRejectionObserver = (reason: Error, promise: Promise<void>) => {
  if (promise === promise1) {
    console.log("promise1 is rejected");
  }
  console.log("reason.name: ", reason.name);
  console.log("reason.message: ", reason.message);
  if (reason.stack) {
    console.log("reason.stack: ", reason.stack);
  }
};

errorManager.on("unhandledRejection", observer);

let promise1 = new Promise<void>(() => {}).then(() => {
  throw new Error("uncaught error")
})

errorManager.off("unhandledRejection");

Or:

import { errorManager } from '@kit.AbilityKit';

let observer: errorManager.UnhandledRejectionObserver = (reason: Error, promise: Promise<void>) => {
  if (promise === promise1) {
    console.log("promise1 is rejected");
  }
  console.log("reason.name: ", reason.name);
  console.log("reason.message: ", reason.message);
  if (reason.stack) {
    console.log("reason.stack: ", reason.stack);
  }
};

errorManager.on("unhandledRejection", observer);

let promise1 = new Promise<void>(() => {}).then(() => {
  throw new Error("uncaught error")
})

errorManager.off("unhandledRejection", observer);

ErrorObserver

type ErrorObserver = _ErrorObserver.default

Defines the ErrorObserver module.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Type	Description
_ErrorObserver.default	ErrorObserver module.

LoopObserver¹²⁺

type LoopObserver = _LoopObserver

Defines the LoopObserver module.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Type	Description
_LoopObserver	LoopObserver module.

UnhandledRejectionObserver¹²⁺

type UnhandledRejectionObserver = (reason: Error | any, promise: Promise<any>) => void

Defines an observer to capture the cause of a rejected promise.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
reason	Error | any	Yes	Generally, the value is of the Error type, indicating the reason for rejection.
promise	Promise<any>	Yes	Rejected promise.