Troubleshooting-Enterprise Mobile Application Studio(EMAS)-阿里云帮助中心

This chapter explains how to troubleshoot problems with the HarmonyOS SDK.

Feature description

The SDK provides two troubleshooting methods: logs and error codes.

Log output

The SDK provides two types of log outputs: HiLog and interface logs.

HiLog log output

The SDK provides a switch that you can use to output SDK logs to HiLog. The following code shows an example:

import { aliyunPushLog } from '@aliyun/push';

aliyunPushLog.enableHiLogLogger();

Call this method before you initialize the SDK. Use this method only for development and testing.

Interface log output

The SDK provides the `addLogger` and `removeLogger` methods to add or remove log output interfaces. The following code shows an example:

import { aliyunPushLog, Logger } from '@aliyun/push'
import hilog from '@ohos.hilog'


class MyLogger implements Logger {
  print(domain: number, tag: string, level: hilog.LogLevel, msg: string): void {
    // This example shows how to output logs to HiLog. The actual implementation depends on the log collection system that your application uses.
    if (level >= hilog.LogLevel.ERROR) {
      switch (level) {
        case hilog.LogLevel.FATAL:
          hilog.fatal(domain, tag, msg);
          break;
        case hilog.LogLevel.ERROR:
        default:
          hilog.error(domain, tag, msg);
          break;
      }
    }
  }
}

const logger = new MyLogger();

// Add the log interface.
aliyunPushLog.addLogger(logger);

// Remove the log interface.
aliyunPushLog.removeLogger(logger);

Follow these recommendations when you use the log interface:

In a production environment, collect only logs at the `hilog.LogLevel.ERROR` level or higher by default.
In a production environment, you can dynamically collect logs at the `hilog.LogLevel.INFO` level or higher for specific devices. To do this, deliver the required configurations to the devices.

Log parameter descriptions

The `domain` for SDK logs is `0xF101`.

The main `tag` for SDK logs is `PS`. This tag identifies logs for SDK interface inputs and outputs.

The SDK outputs logs at the `hilog.LogLevel.ERROR` level if an SDK call fails or a push is abnormal.

Error codes

If an SDK interface call fails, the SDK throws a `PushError`. The following code shows an example for the device registration interface:

import { aliyunPush, PushError } from '@aliyun/push';

aliyunPush.register((err: PushError | undefined) => {
  if (err) {
    console.error(`Failed to register the device. Error code: ${err.code}. Error message: ${err.message}`);
    return;
  }
  console.info(`Device registered successfully. Device ID: ${aliyunPush.getDeviceId()}`);
});

A `PushError` has two main fields:

`code`: The error code. It indicates the type and location of the error.
`message`: The specific error details. This includes information about other exceptions that caused the error.

The following table lists all error codes.

Error code	Error description	Possible cause	Troubleshooting steps
PUSH_001	Unknown error.	A system error or an undiscovered edge case occurred.	Record the error message. Contact EMAS technical support.
PUSH_002	First, initialize the SDK by calling the init method.	Another `Ability` was started directly without initialization.	Check for any `Ability` that might be starting directly. Add the SDK initialization configuration.
PUSH_003	The push data cannot be found.	The provided push parameters are incorrect.	Use logs to confirm the parameters of the interface that reported the error. Confirm that push data exists for the specified parameters.
PUSH_004	You must register the device first.	The `aliyunPush.register` method was not called.	Check if the `aliyunPush.register` method was called. Check if the `aliyunPush.register` method reported an error.
PUSH_005	The data passed to the notification extension is not from Alibaba Cloud Push.	The notification extension message was not pushed from the Alibaba Cloud Mobile Push platform.	Confirm the source of the push data. You can catch the error and adapt your code to handle the data format from other push sources.
PUSH_101_XXX	Feature interface error.	The service response does not match the expected response.	Record the error code and message. Contact EMAS technical support.
PUSH_102	Invalid parameter.	The parameter is invalid.	Check the error message. Use logs to confirm the parameters of the interface that reported the error. Confirm that the parameters are correct.
PUSH_103	Device not registered.	An API that requires device registration was called before the device was registered.	Check if the device registration process was missed.
PUSH_201	Device not registered.	The registration process was interrupted. This caused an inconsistent application state.	Reregister the device.
PUSH_202_XXX	Device registration failed.	The device has an abnormal status on the service.	Record the error code and message. Contact EMAS technical support.
PUSH_203_XXX	Error when enabling or disabling push notifications.	The device has an abnormal status on the service.	Record the error code and message. Contact EMAS technical support.
PUSH_301_XXX	HTTP request failed.	Service interface error.	Retry later.
PUSH_302_XXX	HTTP request failed.	The device cannot connect to the service over the network.	Confirm that the network is working correctly, and then retry.
PUSH_303_XXX	HTTP download error.	The system failed to download the notification image.	The image for this push notification is not displayed. No action is required. If the issue persists, record the error code and message, and contact EMAS technical support.
PUSH_401_XXX	Failed to establish the Alibaba Cloud push channel.	The device is blocklisted.	Restart the application and retry. If the issue persists, record the error code and message, and contact EMAS technical support.
PUSH_402	The Alibaba Cloud push channel is not established.	The device is not registered.	Confirm that the device registration process runs correctly.
PUSH_403_XXX PUSH_404_XXX PUSH_405_XXX	Interface call failed.	The network is unstable.	Retry later. If the issue persists, record the error code and message, and contact EMAS technical support.
PUSH_501_XXX	`dataPreferences` interface call failed.	System interface error.	Check the specific error code and message. Find a solution in the HarmonyOS documentation based on the error message.
PUSH_502_XXX	`notificationManager` interface call failed.	System interface error.	Check the specific error code and message. Find a solution in the HarmonyOS documentation based on the error message.
PUSH_503_XXX	`relationalStore` interface call failed.	System interface error.	Check the specific error code and message. Find a solution in the HarmonyOS documentation based on the error message.
PUSH_504_XXX	`image` interface call failed.	System interface error.	Check the specific error code and message. Find a solution in the HarmonyOS documentation based on the error message.
PUSH_505_XXX	System interface call failed.	System interface error.	Check the specific error code and message. Find a solution in the HarmonyOS documentation based on the error message.