Error handling (4.x)
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.
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 |
| Invalid parameter input | Check the parameters of the current API. For example, the Context for |
| 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 |
| Core component not configured | After you enable |
| Not initialized | Call |
| Deprecated API | A deprecated API was called. Use an API that is supported in the 4.x documentation instead. |
| Duplicate registration call ignored | Check the |
| Internal error | Save the exception and surrounding logs. Check if the SDK and adapter versions match. Troubleshoot based on the specific |
| 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. |
| Registration called outside the main process | This message indicates that the registration process performed a process check. Call |
| Push registration timed out | In Android SDK 4.0.0, when the wait for the ACCS channel result times out, the |
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 |
| Missing parameter | Check the API call and the server-side response to identify the specific missing field. |
| Invalid parameter | Validate the value, length, and format of the parameters according to the API requirements. |
| 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. |
| Tag-related error | Check the tag count, length, target, and API parameters as indicated in the |
| Alias-related error | Check the alias and the bind/unbind operation as indicated in the |
| Server-side internal error | Record the time, API called, error code, and the redacted error message. If the issue persists, contact technical support. |
| Network I/O error | Check network connectivity and the exception details. Investigate environmental factors such as proxies, VPNs, or network changes. |
| Response parsing error | Record the exception information and SDK version. Check for network proxies and inspect the server-side response content. Use the full |
| Other API error | A server-side error that is not individually mapped. The |
| 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 |
| 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. |
| 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. |
| Internal error | Save the exception stack trace and surrounding logs. Troubleshoot in the context of the specific registration or toggle operation. |
| Context is null | Check if |
| 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. |
| 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. |
| Device UTDID conflict | Investigate for device imaging, cloning, or identifier reuse. Record the conflict logs and contact technical support to confirm the resolution method. |
| Device ID is on the blacklist | Contact technical support to check for server-side device restrictions and ask how to recover. |
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 |
|
| Confirm that the registration is successful and that the |
Huawei |
|
| Confirm that the token is not empty. If it fails, record the vendor's |
Honor |
|
| Confirm that a non-empty token is obtained. If it fails, record the |
OPPO |
|
| Successful registration requires both a |
vivo |
|
| Confirm that the |
Meizu |
|
| Check the registration result and confirm that the |
FCM |
|
| 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 |
|
| Token reporting has started. Continue to check the subsequent reporting results. |
|
| 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. |
|
| A connection was not available during reporting. Check the channel initialization and connection status from the same time period. |
|
| 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. |
|
| 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.