---
source_url: https://www.pubnub.com/docs/integrations/mobile-push-notifications/debug-push-notification-messages
title: Debug push notification messages
updated_at: 2026-09-30T07:20:08.000Z
---

# Debug push notification messages

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

This guide shows you how to diagnose why a push sent through [Mobile Push Notifications](https://www.pubnub.com/docs/integrations/mobile-push-notifications/overview.md) isn't reaching a device. You do that by reading the errors FCM and APNs return to PubNub's mobile push gateway. Before you start, confirm:

* Your publish and subscribe key pair has Mobile Push configured.
* Your app is set up correctly in your iOS or Android developer account.
* Your test payload contains the required push payload keys, such as `pn_apns` or `pn_fcm`.

Subscribe to the `-pndebug` companion channel, then publish the test message to the original channel. For continuous monitoring, [forward push errors to your endpoint](https://www.pubnub.com/docs/integrations/mobile-push-notifications/set-up-push-webhooks.md) instead. To check whether a specific device token is still registered, see [Check push device registration](https://www.pubnub.com/docs/integrations/mobile-push-notifications/check-push-device-registration.md). To check whether an FCM payload uses the correct `data` or `notification` keys, see [Check the FCM payload](https://www.pubnub.com/docs/integrations/mobile-push-notifications/check-fcm-payload.md). To rule out PubNub entirely, see [Test mobile push notifications externally](https://www.pubnub.com/docs/integrations/mobile-push-notifications/test-mobile-push-notifications-externally.md).

## Publish to the debug channel

1. Go to the [PubNub Debug Console](https://www.pubnub.com/docs/console/) and subscribe to the channel named `<your-channel>-pndebug`. If you [publish](https://www.pubnub.com/docs/pub-sub/publish/overview.md) to `foo`, subscribe to `foo-pndebug`.
2. Add `"pn_debug": true` to your message payload, at the top level, as a sibling of `pn_fcm` and `pn_apns`, not nested inside either of them:

   ```json
   {
     "pn_debug": true,
     "pn_fcm": {
       "data": {
         "message": "hello"
       }
     },
     "pn_apns": {
       "aps": {
         "alert": "hello"
       },
       "pn_push": [
         {
           "push_type": "alert",
           "auth_method": "token",
           "targets": [
             {
               "environment": "development",
               "topic": "com.PubNub.MobilePushTest"
             }
           ],
           "version": "v2"
         }
       ]
     }
   }
   ```

3. Publish the message to channel `foo` (not `foo-pndebug`). Publish from your client, your server, or the Debug Console itself. Debug messages arrive on `foo-pndebug` almost immediately.

## Read the debug channel output

Check the message count first. A successful delivery reports how many registered devices received the push on each provider:

```text
Devices found for push notification apns: 2 fcm
```

If a device or the whole push failed, look for an error message instead. These are examples of the responses FCM and APNs send back to PubNub's mobile push gateway:

```text
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
```

If the publish call itself returns HTTP 400 Bad Request, read the text description in the response body. Common causes are an invalid `type` argument, a missing `channels` value, or an invalid device token.

## Related tasks

* [Check push device registration](https://www.pubnub.com/docs/integrations/mobile-push-notifications/check-push-device-registration.md). Confirm whether a device token is still registered on the channels you expect.
* [Forward push errors and device removals to your endpoint](https://www.pubnub.com/docs/integrations/mobile-push-notifications/set-up-push-webhooks.md). Send push errors and device-removal events to your endpoint.
* [Check the FCM payload](https://www.pubnub.com/docs/integrations/mobile-push-notifications/check-fcm-payload.md). Confirm your FCM message uses the correct `data` or `notification` keys.
* [Test mobile push notifications externally](https://www.pubnub.com/docs/integrations/mobile-push-notifications/test-mobile-push-notifications-externally.md). Send directly to FCM or APNs to rule out PubNub.
* [Send push notifications on iOS](https://www.pubnub.com/docs/integrations/mobile-push-notifications/send-push-notifications-ios.md). Configure APNs credentials and register a device.
* [Send push notifications on Android](https://www.pubnub.com/docs/integrations/mobile-push-notifications/send-push-notifications-android.md). Configure FCM credentials and register a device.
* [Mobile push notifications](https://www.pubnub.com/docs/integrations/mobile-push-notifications/overview.md). How Mobile Push Notifications bridges pub/sub with APNs and FCM.
* [API limits](https://www.pubnub.com/docs/architecture/limits.md#mobile-push). Push credential and payload size limits.

Last updated at: 2026-09-30T07:20:08.000Z