Technical FAQ

This FAQ is organized around a practical troubleshooting flow: prepare required information, locate the push chain stage, and then handle the specific issue. When "push succeeds but users do not receive it", start with the basic checks before moving to a specific scenario.

If you are deciding which capability to use for a business scenario, see Product and Scenario FAQ. If you already have error codes, delivery failures, vendor-channel issues, or click-navigation issues, start here.

Quick Navigation

Troubleshooting Preparation

What information should I prepare before troubleshooting?

Prepare the following information first. It can significantly reduce back-and-forth confirmation:

• AppKey.
• Message ID, which is the msg_id returned by the API or shown in Push Records.
• Current valid Registration ID of the target device.
• Push time, platform, device model, OS version, app version, and SDK version.
• Push request body or screenshots of console push configuration.
• Message lifecycle result from the troubleshooting tool.
• Client logs and vendor token acquisition status.

Related documents:

• Troubleshooting Tools
• Push Troubleshooting

How do I get AppKey, Registration ID, and Message ID?

• AppKey is available in the app information section of the Jiguang console.
• Registration ID is obtained after the client initializes JPush successfully. It identifies the current app on the current device for push.
• Message ID can be obtained from the msg_id returned by the API or from Push Records in the console.

For details, see Required Parameters for Troubleshooting.

How do I get client logs?

If integration or message receiving is abnormal, collect client logs for initial troubleshooting. If logs do not identify the cause, provide them together with AppKey, Message ID, and Registration ID to technical support.

For log collection, see Client Log Collection.

Delivery and Channels

The push API returns success, but the user did not receive the message. What should I check first?

A successful Push API response means JPush accepted and processed the request. It does not mean every device received or displayed the notification.

Recommended troubleshooting flow:

1. Save the msg_id returned by the API.
2. Obtain the current valid Registration ID of the target device.
3. Use Message ID + Registration ID in the troubleshooting tool to query the message lifecycle.
4. Use Device Query to confirm whether the device belongs to the current AppKey, whether it is online, whether notification permission is enabled, and whether the vendor token is normal.
5. Check Push Records and loss reasons to identify whether the issue happened during request, targeting, channel delivery, delivery, or display.

Related documents:

• Push Troubleshooting
• Troubleshooting Tools
• Push Records

Why can I receive push when the app is open but not after the app is killed?

If only the JPush proprietary channel is integrated, timely delivery depends on the app long connection being online. When the app is killed by the system or the long connection is offline, messages are cached on JPush servers and delivered when the app comes online again.

If you need best-effort offline delivery:

• Integrate the corresponding Android vendor channel.
• Check whether the third_party_channel delivery strategy matches expectations.
• For offline reminders based on custom messages, use custom-message-to-vendor-notification.
• For must-reach scenarios, configure SMS fallback.

Related documents:

• Notification Delivery Strategy
• Custom Message to Vendor Notification
• Cannot Receive Push While Offline

Why did the message not use the vendor channel?

Common causes include vendor SDK integration failure, missing vendor token, incorrect vendor parameters, mismatched delivery strategy, non-VIP vendor-channel resource limits, or insufficient vendor quota.

Check:

• Whether the client integrated the corresponding vendor SDK successfully.
• Whether Device Query shows the corresponding vendor token.
• Whether vendor channel configuration in the console is correct.
• Whether distribution under options.third_party_channel matches expectations.
• Whether current vendor quota, QPS, and message classification are restricted.
• Whether a non-VIP app has triggered vendor-channel delivery limits.

Related documents:

• Vendor Channel SDK Integration Guide
• Vendor Quota and QPS Limits
• Vendor Message Classification and Quota Management
• Push API v3 - third_party_channel

The push reached the device but was not displayed in the notification tray. How should I troubleshoot?

Delivery is not the same as display. Notification-tray display issues are usually related to notification permission, system notification channels, foreground display logic, vendor restrictions, content rules, or device system policies.

Check:

• Whether device notification permission is disabled.
• Whether the correct NotificationChannel is configured on Android 8.0 and later.
• Whether notification content complies with vendor rules and avoids meaningless content such as pure numbers, test, or 测试.
• Whether the app handles display logic itself while in the foreground.
• Whether the vendor channel returned failures related to content, classification, or permission.

Related documents:

• Reaching Users with Notification Permission Disabled
• Android API
• Notification Display Issues

Is failure to receive custom messages the same issue as failure to receive notifications?

Not exactly. Notifications can be displayed in the notification tray. Custom messages are not displayed in the notification tray by default and usually depend on the client callback after the app is online.

Check:

• Whether the client implements the custom message callback.
• Whether the app is online and the long connection is normal.
• Whether offline users are expected to be reminded. If yes, use custom-message-to-vendor-notification.
• Whether only some vendors support delivering custom messages through vendor channels.
• Whether the server mistakenly sends both notification and notification_3rd.

Related documents:

• Custom Message to Vendor Notification
• Push API v3

Targets and Parameters

Push returns 1011 and says no target user was found. How should I handle it?

1011 usually means there are no matching push targets. For example, the Registration ID does not belong to the current AppKey, the alias or tag was not bound successfully, the target user has been inactive for a long time, or the push condition does not match the actual binding value.

Check:

• Whether the Registration ID belongs to the current AppKey.
• Whether the target device was reinstalled, cleared data, or re-registered.
• Whether alias, tag, or segment values match what the client actually reported.
• Whether the push target is empty or the condition is too narrow.
• Whether the target user has been inactive for a long time.

Related documents:

• Tag and Alias Usage Guide
• Device API
• 1011 Error Troubleshooting

Tag or alias push does not hit the target. How should I troubleshoot?

Common tag and alias issues include binding failure, binding not yet effective, binding count limits, mismatch between target value and push value, and missing rebinding after device re-registration.

Check:

• Whether the callback result for setting tag or alias on the client is successful.
• Whether multi-device binding for the same user matches business expectations.
• Whether tag or alias case, special characters, and length are correct when pushing.
• Whether user identity is synchronized again after Registration ID changes.
• Whether Push Records show target conditions matching the original push.

Related documents:

• Tag and Alias Usage Guide
• Device API
• Tag/Alias Setup Issues

Click and Display

Vendor-channel notification click does not navigate. How should I troubleshoot?

Vendor-channel click navigation usually requires both client and server configuration to be correct.

Check:

• Whether the client configured the target Activity, action, scheme, or deeplink.
• Whether the server sends intent according to Android Notification Click Action.
• Whether OPPO, FCM, or other channels pass action or full Activity name as required.
• Whether third_url_encode is used when jump parameters contain special characters such as # or ;.
• Whether the landing page can restore business context through notification extras.

third_url_encode example:

          {
  "extras": {
    "third_url_encode": true
  }
}

        

How do I set a custom ringtone?

Only the JPush channel and some vendor channels support custom ringtones. Different vendors have different restrictions on ringtone file path, first notification-channel creation, system version, and related behavior. For details, see Custom Ringtone.

How do I set notification images?

JPush supports large images, right-side icons, status-bar small icons, and related capabilities. Support varies by vendor and system version. For details, see Icon Settings.

iOS

iOS push environment mismatch（errcode: -16）. How should I handle it?

If the troubleshooting tool shows -16 iOS push environment mismatch, the environment of the registered device token usually does not match the APNs environment selected by the push request.

Check:

• Whether the installed app package is for development or production.
• Whether the certificate or Token Authentication configuration matches the Bundle ID.
• Whether options.apns_production in the API request is set correctly.
• Whether the test device reinstalled the app and obtained a new token.

Related documents:

• iOS API
• Push API v3
• iOS Push Environment Issues