Mobile Push Troubleshooting

If you have issues sending to devices through the PubNub Mobile Gateway, try these debug techniques. They bypass Mobile Push Notifications logic to confirm your device tokens, app setup, and certificates are correct.

Whether or not the issue is on PubNub’s side, we’re happy to help. Sharing the results of these tests in your support ticket can save time and speed up root‑cause analysis.

If you test mobile push notifications and don’t receive them on a device, confirm the following:

  • You're using the proper PubNub API keys (publish and subscribe keys)
  • Mobile Push is correctly configured for those keys
  • Your app is correctly configured in your iOS or Android developer account
  • The test payloads are correctly formatted the necessary push payload keys/values

Debug messages​

Publish debug messages to a special channel to troubleshoot push issues, such as invalid device tokens or malformed payloads.

  1. Go to the PubNub Debug Console and subscribe to the -pndebug channel. If the channel you're publishing to is foo, subscribe to foo-pndebug.

  2. Add "pn_debug":true to your message payload at the top level.

    {
    "pn_debug":true,
    "pn_fcm":{
      "data":{
         "message":"hello"
      }
    },
    "pn_apns":{
      "aps":{
         "alert":"hello"
      },
      "pn_push":[
         {
            "push_type":"alert",
            "auth_method":"token",
    show all 26 lines

  3. Publish the message to channel foo. You can publish from your client, server, or the Debug Console. You should see error messages in the console.

Successful device registrations​

This message shows how many registered devices received the push on each provider:

Devices found for push notification apns: 2 fcm

Errors​

These examples show the kinds of responses FCM and APNs can send back to PubNub’s mobile push gateway:

fcm Error: InvalidRegistration Devices: null
fcm WARNING error: NotRegistered, sub_key: sub-c-..., channel: my_channel, reg_id: APA91bHRRxfHHB_T0AVojoJx..., timetoken: 14567269547473296
apns INFO Certificate for sub-c-... valid (expiration: Sep 14 08:58:26 2016 GMT)
apns ERROR Error on APNs send for subkey sub-c-... / channel gone_fishing / device 2a0a6234ffdb85df6624cf0546...: invalid token

HTTP 400 Bad Request​

The API returns HTTP 400 for input validation errors. The response body usually includes a text description. Common causes include:

  • Invalid type argument
  • Channels missing
  • Invalid device token

Push webhooks​

For automated monitoring of push issues, set up Push Webhooks. Webhooks provide real‑time alerts when devices are unregistered or push errors occur. They complement the manual Debug Console approach above.

You can set up Push Webhooks in the Admin Portal. After configuration, your endpoint receives webhook events for push errors or when push devices are unregistered or removed.

  • A push device is removed:

    {
       "sub_key":"sub-c-e1559b02-3320-11ea-b686-76f717eaed2c",
       "timestamp":"16007987966269679",
       "platform":"apns2",
       "action":"remove",
       "device":"f3b26d22f3b26d22f3b26d22f3b26d22f3b26d22f3b26d22f3b26d22f3b26d22"
    }

  • A message is sent with an invalid APNs2 payload:

    {
       "type":"error",
       "platform":"apns",
       "timestamp":"16008987759817415",
       "msg":"APNs2 payload error: pn_push must be a list",
       "channel":"mangai2",
       "sub_key":"sub-c-4db1663a-b2f4-11e9-ab7b-1ef11a8ab0d1",
       "devices":""
    }

  • An FCM device is updated with a new device token:

    {
    "sub_key" : "sub-c-...",
    "action" : "update",
    "old_device": "APA91bEgK4D",
    "device" : "ta28zYhV",
    "platform" : "gcm",
    "timestamp" : 1441230130
    }

Check device registration​

You can check if a device is still registered to channels after you publish a push notification. Use a simple REST URL in the browser.

In the following cURL command, push_type is gcm, apns2, or apns. device_reg_token is the device token. The command returns all channels the device is still registered for (for the given push type).

curl 'http://ps.pndsn.com/v1/push/sub-key/{your_sub_key}/devices/{device_token}?type={push_type}'

Example of response:

["channel1","channel2","channel3"]

If the list is empty, the device token is likely invalid or not registered. APNs or FCM may have marked it invalid, and PubNub unregistered it from all channels. The -pndebug channel should reveal the reason.

Check FCM payload​

After you configure FCM, you may not see the notifications you send. Before you troubleshoot with PubNub, confirm the FCM message type. The following is an excerpt from the Firebase documentation:

"With FCM, you can send two types of messages to clients: Data or Notification. Notification messages are sometimes thought of as display messages. These are handled by the FCM SDK and displayed automatically. Data messages, which are handled by the client app. Notification messages contain a predefined set of user-visible keys. Data messages, by contrast, contain only your user-defined custom key-value pairs. Notification messages can contain an optional data payload. Maximum payload for both message types is 4KB, except when sending messages from the Firebase console, which enforces a 1024 character limit."

Your app may send or handle the wrong message type. In an FCM payload, you can use one or both of these keys: data or notification.

{
  "pn_fcm" : {
    "notification": {
      "title":"Portugal vs Denmark",
      "body":"great match!"
    },
    "data" : {
      "room" : "Portugal vs Denmark",
      "body" : "great match!"
    }
  }
}

Use data or notification (or both, depending on your use case). If you send only data, your code must display the push. If you send notification, Android displays it automatically.

Background notifications​

If a device is registered for Mobile Push via FCM or APNs and the app is subscribed to the same channel, the device receives the message twice: once via Mobile Push and once via the PubNub SDK. Add client‑side de‑duplication logic.

If de‑duplication isn’t the cause, test outside PubNub to isolate the issue.

Testing mobile push notifications without PubNub​

Often the cause is an invalid registration token (APNs or FCM), duplicate tokens, or an expired certificate or key. Testing outside PubNub is the fastest way to isolate the issue.

Testing FCM​

Use the following cURL command (from Google’s FCM page) to publish a message to FCM, bypassing PubNub infrastructure. The command requires a registration ID.

Legacy FCM:

curl --header "Authorization: key=<API_KEY>"\
  --header Content-Type:"application/json"\
  https://fcm.googleapis.com/fcm/send\
  -d "{\"registration_ids\":[\"ABC\"]}"

HTTP v1:

Refer to Firebase docs to generate an OAuth access token and then send a push notification.

You can also use these tools to test FCM push notifications:

Testing APNs​

Use this script to publish a message to APNs, bypassing PubNub infrastructure. It requires an APNs certificate and an iOS device token.

For APNs, you can run a Python script that uses your push certificate (.pem file) to verify the certificate. Optionally, specify a device token to receive a test push.

For richer UI tools, use APNs test apps for Mac (App Store) or online web apps. Also see Apple’s Troubleshooting Mobile Push Notifications.

Last updated on
On this page