Push notifications are not sending

Push notifications are a great tool for re-engagement. With Leanplum users can easily create personalized and engaging push campaigns from the Dashboard. While testing these campaigns, the push might not be received on the targeted device. In this troubleshooting article we will go over how to track down the cause for this and resolve the problem.

How Leanplum handles push notifications

In order to be able to troubleshoot efficiently, we need to go over how Leanplum handles the push notifications on iOS and Android. Having this information makes identifying the potential issue easier.

The Leanplum push notification process consists of two parts - going through our backend pipeline to send it to the correct target users and being handled by the Leanplum SDK in the app itself.

  • The push pipeline - After the message is sent from the dashboard it goes to the Leanplum backend push pipeline. It evaluates the targets for the message, calculates the optimal time for delivery(if enabled), schedules messages etc. When the time comes, the message is sent to GCM or APN respectively.
  • The Leanplum SDK - When the app receives the push notification, the Leanplum SDK is responsible for handling it - receive the push notification, show it, track the open and send it to Leanplum, perform the open action etc.

The Leanplum SDK is integral part in handling the push notifications, that is why it is important the instrumentation is done correctly and the SDK is configured for push as described in the Leanplum documentation.

  • Android - The SDK handles the push with a Leanplum Push Receiver and Leanplum Listener Service. They handle the push on the app’s behalf and ensure that the Push Open is tracked correctly. Ensure that the manifest contains the required entries outlined in the documentation: SDK setup. In addition to that, it is important to set the FCM Sender Id(or Ids) as noted in the documentation: Push notifications
  • iOS - ensure that the app delegate contains the required code to handle the push notification: Push notifications and that the push certificates are uploaded to the Leanplum Dashboard.

Having a misconfiguration in the SDK instrumentation in the app can result in the push notification not being received or shown, even though it has been sent by the push pipeline.


It is important to note that immediate delivery push notifications may take up to 15 minutes to be delivered.

With this information in hand we can start troubleshooting push notification problems. The best way to check if push notifications are working correctly is by targeting a push message directly to a specific user. In the Leanplum Dashboard users tab locate your userId and send an immediate message to that user.

Check if the push message has been sent by the Leanplum Push Pipeline

Check the message page for the fast counter indicating the number of sent messages. This information can be found in the top right corner of the message page under the View Results Button:


This counter indicates the number of messages that were sent out by the Leanplum push pipeline.

Keep in mind that it can take up to 15 minutes for the message to be sent out. If after this time, the counter does not indicate that the message has been sent, this means that the message has not been sent by our pipeline. There might be a problem with the Google Cloud Messaging settings/Apple Push Certificates:

  • If you are using a custom GCM senderId, go to your application settings’ Push Notification tab and verify that the Google API key is correct. If you are using the default Leanplum GCM SenderID, the field should be empty. Check if there are no trailing or starting white spaces. Copying the code from the Google page can sometimes result in whitespaces at the start of the code.
  • Verify that Apple Push Certificates are uploaded to Leanplum and the password used is the correct one by going to your app settings’ Push Notification tab.

In the event that the push has not been sent by the Leanplum pipeline, the above causes are most likely since these configurations are required by the Leanplum backend.

Check if the target device has Push Token/Android GCM registration id

If the message has been sent by the Leanplum Push Pipeline it relies on the iOS Push Token/Android GCM registration id to deliver the message. Go to the Users tab of your app and find the user that was in the target for the push notification and check if the Push Token/Android GCM Registration id values are present.

If the token/id is missing, the push notification cannot be sent. To ensure that the token is added, check if the app has notification permissions and start it one more time. On iOS the Push Token is paired with the certificate so it is possible that the app was ran before the certificates were uploaded to Leanplum. If this is the case, run the app again after the certificates have been set and the token should appear.

Double check if the push notification has been configured as described in the documentation. On Android it is important to ensure the required entries in the Manifest are added: Android SDK setup.

For iOS if there is a token present, you can use the open source tool NWpusher to verify if the token works with the certificates uploaded to Leanplum: https://github.com/noodlewerk/NWPusher

The tool allows you to bypass the Leanplum push pipeline and send a push directly to the token, verifying if the token is paired correctly with the push certificate.

Using it is very simple, after installing the latest version, add the push certificate and enter the push token from your user profile and send the message. If there is a problem, an error will be shown in the tool, otherwise the test push should arrive on the target device.


Note to consider:

Only one device profile can have a push token, this is determined by the latest user that logged in on that device. If the device is associated with multiple user profiles, the one that is being targeted might not be the one with the push token. Check the different user profiles by performing a User search with the device id.

Message is sent, device has token but message is not received

This scenario indicates that there is most likely an instrumentation problem in the app itself. The push reaches the device but it is not displayed. This could be caused by customization the push message logic or on Android by the use of custom PushListener/PushNotificationReceiver and not the ones required by Leanplum. It is important to double check the Leanplum documentation and ensure that the SDK is instrumented properly.

On Android, you can use ADB to check if the message bundle has been received. Set the device for debugging, connect it and sent a push notification. When the notification is received, you will be able to see in the logs a message from Leanplum:

I / Leanplum: Received: Bundle[{
	lp_version = 1,
	lp_message = Push Test Message,
	lp_messageId = 4881066985259008, //example messageId
	_lpn = 4881066985259008, //example lpn
	_lpx = {
		"__name__": ""
	collapse_key = do_not_collapse

If the bundle is received but no notification is displayed, it is worth checking any customization that is being done to the push or if there is a custom notification listener/receiver. It is possible that they intercept the push and handle it instead of the Leanplum SDK, which could cause the message to no appear or Push Open occurrences to not be tracked.

Android - double check if you are using multiple senderIds. If this is the case, ensurethat the senderIds are set correctly using the method LeanplumPushService.setGcmSenderIds.


Google API Key

If you are using a custom senderId, you have also set the Google API Key in the push settings. You can easily verify if this key correctly authenticates to GCM by following this documentation article: https://developers.google.com/cloud-messaging/http#auth the “Checking the validity of an API key” section.

Manual push notification is not being sent/delivered

When you have a manual push that should be triggered via an API call from your server, it is important to check the response of this call. If the message was successfully sent to the Leanplum pipeline a Success response will be returned. In the case of a problem when the call is received, the error response will be returned.

Another consideration to have in this case is that if you have any dynamic values in the message, ensure that they are correctly replaced in the message and that the API call contains the correct payload for these values.