Error handling (4.x)

Updated at:

This article describes errors related to initialization, APIs, the ACCS channel, and vendor tokens in the Mobile Push Android SDK 4.x. It also explains how to use the unified log tag EMAS_PUSH for troubleshooting.

Obtain callbacks and logs

This topic applies to Mobile Push Android SDK 4.x. The following error codes and callback behaviors use the released version 4.0.0 as a baseline. First, determine the actual dependency version of your application. Then, record the API where the error occurred, the two parameters of the CommonCallback.onFailed(String errorCode, String errorMessage) method, and the time of occurrence. PUSH_00000 is the success code defined by the SDK. Your code should determine the result based on the success callback of the corresponding API.

Set the log level after PushServiceFactory.init is complete, and before register and vendor channel registration. setDebug(true) is used for component and parameter checks during integration, and the log output level is set by using setLogLevel. Run the following example after you complete initialization in the Application:

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.setLogLevel(CloudPushService.LOG_DEBUG);
pushService.setDebug(true); // Optional: For debugging components and parameter configurations.
pushService.register(getApplicationContext(), new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        // Confirm the registration result in the main process before you read pushService.getDeviceId().
    }

    @Override
    public void onFailed(String errorCode, String errorMessage) {
        // PushDemo is a custom tag for your application and is not a unified SDK tag.
        Log.e("PushDemo", "register failed: " + errorCode + " | " + errorMessage);
    }
});

Use tag:EMAS_PUSH level:DEBUG in Android Studio Logcat to view the SDK logs, and use the following filter conditions on the command line. For example, the logs for a custom application callback such as PushDemo must be viewed separately or by adding its TAG to the command.

adb logcat -v threadtime "EMAS_PUSH:D" "*:S"
# To view failure callbacks from the sample application simultaneously:
adb logcat -v threadtime "EMAS_PUSH:D" "PushDemo:D" "*:S"

The 4.x SDK consistently uses the TAG EMAS_PUSH, and module names such as [AppRegister] and [AgooChannel] are included in the log message body. Logs from vendor native SDKs, the Android system, and the application use their own TAGs. After you finish debugging, lower the log level. LOG_OFF disables output only from the SDK's unified logging pipeline, and logs from other sources are controlled by their respective logging configurations.

Important

4.x does not use legacy MPS:, awcn, AUTH_SUCC, ACCS/SPDY logs, or old channel values as the success criteria for a channel. For information about handling legacy 1105, 10207, and ACCS errors, see Error Handling (3.x). For information about upgrade changes, see Android SDK 4.x Upgrade Guide.

Initialization and API call errors

The following table lists common error codes in Android SDK 4.0.0 and their solutions. The errorMessage contains specific parameters, server-side responses, or exception details. When troubleshooting, record both the error code and the full error message.

Error code

Description

Solution

PUSH_20101

Invalid parameter input

Check the parameters of the current API. For example, the Context for register cannot be null.

PUSH_20103

Invalid appversion parameter

Check the application version number. It cannot be null and its length must not exceed 32 characters. This check is performed when setDebug(true) is enabled.

PUSH_20106

Core component not configured

After you enable setDebug(true), the SDK checks for required components. Verify the final merged AndroidManifest.xml and the dependency and obfuscation configurations for the main SDK and vendor adapters against the 4.x integration guide.

PUSH_20108

Not initialized

Call PushServiceFactory.init in the current process before you obtain the CloudPushService instance and call its related APIs.

PUSH_20109

Deprecated API

A deprecated API was called. Use an API that is supported in the 4.x documentation instead.

PUSH_20110

Duplicate registration call ignored

Check the register calls in your Application, business entry points, and multi-process logic to ensure that the registration process is triggered only once. The SDK automatically retries registration. Before your application initiates a manual retry, resolve the error based on the failure callback and logs.

PUSH_10114

Internal error

Save the exception and surrounding logs. Check if the SDK and adapter versions match. Troubleshoot based on the specific errorMessage.

PUSH_10115

Abnormal channel registration state

Review the complete logs from the start of registration to the failure. Check the call sequence, duplicate registrations, and the ACCS initialization result.

PUSH_10119

Registration called outside the main process

This message indicates that the registration process performed a process check. Call PushServiceFactory.init in each process, but check the register result only in the main process.

PUSH_10120

Push registration timed out

In Android SDK 4.0.0, when the wait for the ACCS channel result times out, the errorMessage contains "channel timeout". Check the network status at the time of the error and review the logs for the connection establishment and registration process.

Note

When a non-main process receives onSuccess, continue to verify the registration and message receiving results in the main process. Initialize each process according to the Application initialization requirements.

If you encounter PUSH_10109 (Network connection failed) or PUSH_20107 (Push service closed due to continuous crashes), please record the complete error logs and the versions of the main SDK, auxiliary channel SDK, and vendor extension package, and contact technical support for troubleshooting.

Server-side API and network request errors

Error code

Description

Solution

PUSH_10101

Missing parameter

Check the API call and the server-side response to identify the specific missing field.

PUSH_10102

Invalid parameter

Validate the value, length, and format of the parameters according to the API requirements.

PUSH_10103

Client and server-side signatures mismatch

Verify that the AppKey and AppSecret belong to the same application. Ensure that the build variant and initialization configuration match the target environment. Redact secret keys from logs before sharing them.

PUSH_10104

Tag-related error

Check the tag count, length, target, and API parameters as indicated in the errorMessage.

PUSH_10105

Alias-related error

Check the alias and the bind/unbind operation as indicated in the errorMessage.

PUSH_10106

Server-side internal error

Record the time, API called, error code, and the redacted error message. If the issue persists, contact technical support.

PUSH_10107

Network I/O error

Check network connectivity and the exception details. Investigate environmental factors such as proxies, VPNs, or network changes.

PUSH_10108

Response parsing error

Record the exception information and SDK version. Check for network proxies and inspect the server-side response content. Use the full errorMessage to identify the cause.

PUSH_10118

Other API error

A server-side error that is not individually mapped. The errorMessage contains the server-side error code and message, which should be recorded together.

PUSH_10121

Network request failed.

Check the network error details for requests such as fetching device information and review the SDK logs from the same time period.

The errorMessage may contain specific error information from the server. If a parameter or business validation fails, first correct the parameter or business configuration. If a network failure occurs, retry based on your application's policy.

ACCS proprietary channel errors

In 4.x, the proprietary channel uses an ACCS persistent connection. The following table lists channel-layer error codes. The format of error codes in the register callback is explained after the table. For connection changes that occur after registration is complete, troubleshoot using connection logs from that time period.

Error code

Description

Solution

PUSH_30001

The server returned a business error.

Check the server-side error details for the same operation. This can occur during operations such as registration or toggling the push service. Record the specific API that was called.

PUSH_30002

Persistent connection network error

Check if an ACCS connection exists, verify the network status, and investigate the cause of the exception. Use connection establishment or request failure logs to locate the issue.

PUSH_30003

Internal error

Save the exception stack trace and surrounding logs. Troubleshoot in the context of the specific registration or toggle operation.

PUSH_30004

Context is null

Check if PushServiceFactory.init has completed in the current process and if the correct Application context is being used.

PUSH_30005

Persistent connection channel not ready

This error can occur when you enable or disable push notifications. First, complete the registration in the main process and confirm that the ACCS channel is ready before toggling push notifications.

PUSH_30006

Invalid device UTDID

When the SDK receives this reason for closure, it attempts to regenerate the UTDID. Verify by completely closing and restarting the application. If the issue persists, save the logs and contact technical support.

PUSH_30007

Device UTDID conflict

Investigate for device imaging, cloning, or identifier reuse. Record the conflict logs and contact technical support to confirm the resolution method.

PUSH_30008

Device ID is on the blacklist

Contact technical support to check for server-side device restrictions and ask how to recover.

Important

In Android SDK 4.0.0, the register process adds a PUSH_ prefix to channel error codes. For example, if the channel returns PUSH_30002, the error code in the registration failure callback is PUSH_PUSH_30002. Interfaces that directly pass channel results, such as the push notification switch, use a single prefix, for example, PUSH_30005. When troubleshooting, record the API call, the original errorCode, and errorMessage, and identify the error based on the format of the corresponding interface.

When a connection fails to be created, the registered callback may also return a symbolic error code. For example, CONNECTION_CREATION_FAILED is converted to PUSH_CONNECTION_CREATION_FAILED during the registration process. Exception types in the ACCS logs include CONNECTION_ALREADY_CLOSED, CONNECTION_ALREADY_EXISTED, CONNECTION_NOT_EXISTED, CONNECTION_CREATION_FAILED, READ_TIMEOUT, WRITE_TIMEOUT, and INTERNAL_ERROR. Some exceptions are converted into general channel errors before being returned to the application. To identify the specific cause, use the errorCode and errorMessage from the callback and the connection logs from the same time period.

In the log body, locate the [AgooChannel] module, search for keywords such as Failed to build, AgooChannel initialization failed, connection closed:, and Channel not ready, and use the adjacent logs to determine whether the error occurred during the connection establishment, registration, push notification switch, or connection closing stage.

Troubleshoot vendor registration and token reporting

Error codes from vendor SDKs are not the same as the unified PUSH error codes. The unified log tag only standardizes the log entry point; it does not alter the error codes or their meanings returned by vendors. First, confirm that vendor registration returns a valid token. Next, verify that the SDK reports the token to EMAS. Finally, send a test push to validate message reception, display, and clicks.

Vendor

Log module

Registration keyword

Key check

Xiaomi

[MiPushBroadcastReceiver]

onReceiveRegisterResult regId:

Confirm that the registration is successful and that the regId is valid.

Huawei

[HuaWeiRegister] / [HuaweiPushMessageService]

onToken appId: / onToken token:

Confirm that the token is not empty. If it fails, record the vendor's statusCode or exception information.

Honor

[HonorRegister] / [HonorPushMessageService]

onToken appId: / onToken token:

Confirm that a non-empty token is obtained. If it fails, record the errorCode and errorMsg and troubleshoot the cause.

OPPO

[OppoRegister]

onRegister code=0 regid=

Successful registration requires both a code of 0 and a valid registration ID (regid). If the regid contains error text, troubleshoot based on the error message.

vivo

[VivoRegister] / [PushMessageReceiverImpl]

onReceiveRegId regId:

Confirm that the regId is valid and check the results of turnOnPush and getRegId, as well as any onFailed information.

Meizu

[MeizuPushReceiver]

onRegister status:

Check the registration result and confirm that the pushId is a valid registration identifier.

FCM

[GcmRegister]

fcm token is

Confirm that a non-empty token is obtained and proceed to check the result of reporting it to EMAS.

The keywords in the table help locate vendor registration logs. Confirm the registration result by checking both the returned status and the validity of the token. If registration fails, record the original error code and error message from the vendor, and verify the configuration in the respective vendor's platform.

Stage

Log keyword

Description and solution

EMAS_PUSH / [AgooChannel]

reportThirdToken: type=

Token reporting has started. Continue to check the subsequent reporting results.

EMAS_PUSH / [AgooChannel]

Channel not ready, enqueuing token request:

The proprietary channel is not ready, so the SDK has queued the token reporting request. Continue to check the main process registration and the ACCS channel status, and monitor for subsequent processing.

EMAS_PUSH / [AgooTokenReportService]

connection not found

A connection was not available during reporting. Check the channel initialization and connection status from the same time period.

EMAS_PUSH / [AgooChannel]

Token report success:

The SDK's token reporting request and response process is complete. Next, verify the device information in the console and send a test notification to validate reception, display, and clicks.

EMAS_PUSH / [AgooChannel]

Token report failed: / Token report error:

Reporting was not completed or an exception occurred. Continue by checking for reporting service exceptions and ACCS logs from the same time period.

Successful vendor token registration and successful data reporting to EMAS are two different stages. After you confirm that data is reported, verify the applicable channel when the app is in the foreground, in the background, or when its process is killed. You must also check system notification permissions, Android notification channel configurations, and the notification content. In version 4.x, all notification click events are handled in the onNotificationOpened callback. However, for notifications from native vendors such as Xiaomi, Huawei, Honor, OPPO, vivo, and Meizu, you must still correctly configure a transit Activity to handle clicks. The legacy onSysNoticeOpened callback is used only in version 3.x. FCM data messages do not require this Activity.

Submit troubleshooting information

If the issue persists, provide the exact versions of the main SDK and vendor adapters, the Android version and device model, the API where the error occurred, the running process, when the error occurred, and the original errorCode/errorMessage. Also, include relevant logs from initialization to the point of failure. Specify whether a valid DeviceId was obtained, whether the vendor token was obtained and reported, and at what stage the problem occurs: reception, display, or click.

DeviceId, UTDID, and vendor tokens are different identifiers and cannot be used interchangeably. Before submitting, redact sensitive information from logs, such as device identifiers, account details, tokens, and business content. Do not provide secret keys such as the AppSecret. Include only the debug logs necessary to locate the issue.