Export (0) Print
Expand All

Debugging Notification Hubs

Updated: October 13, 2014

This section describes some tips on debugging a solution that uses Azure Notification Hubs.

Debugging push notifications can be a challenge because so many systems are involved: your device app, your back-end, the platform notification system, and most likely a push notification service such as Azure Notification Hubs. In a typical scenario, it can take several hours to set up your notification hub with the correct push credentials, for your device app to register with the platform notification system and with the hub, and finally, for your back-end to send a notification. After performing these steps, you still might not see anything appear on your phone.

To help diagnose the issue, you can use either the Debug tab in the Azure Management Portal, the Service Bus Explorer tool, or some combination of the two.

Azure Management Portal

You can use the Azure Management Portal to send test notifications. You can access this capability in the Debug tab of your notification hub:


You can specify which Push Notification Service you want to use when sending the test notification: Windows Phone, Windows, iOS, Android, or custom (using a template). You can send a random test notification, or you can send test notifications to a specific set of registrations. To send a test push notification, set the required parameters in the Debug tab, then click Send at the bottom of the screen.

Result Codes

When you send a test notification from either the portal or the Service Bus Explorer, the outcome is returned as a success or failure. The following table lists the possible outcomes and their meaning:


Outcome class Description


The notification was delivered successfully to the PNS.


The PNS did not accept the notification because the associated credentials are being throttled.


The PNS did not accept the notification because the target channel (ChannelUri, device token, …) is being throttled.


The PNS did not accept the notification because the channel is currently disconnected.


The PNS did not accept the notification because the channel queue is full.

PNS problems


A connection to the PNS cannot be established.


An error in Service Bus interface with the PNS.


The PNS reported an internal error.


The PNS reported that the service is not available.

PNS authentication problems


If an authorization token must be obtained before contacting the PNS (e.g. WNS), this error occurs if it is impossible to reach the service to obtain that token.

Note: This is not the outcome when the credentials are wrong.


An error in the Service Bus interface with the token provider service.


The credentials specified in the registration do not exist, they are blocked, or Service Bus was not able to use them successfully (forexample, the PNS refused them or the service providing the authorization token refused them).


If an authorization token must be obtained before contacting the PNS (e.g. WNS), this error occurs if the PNS refuses the token.


The token provided to the PNS is valid but does not grant any rights to the specified PNShandle.

PNSHandle problems


The PNS does not recognize the provided PNSHandle as a valid PNShandle.


The PNS recognizes the PNSHandle, but the PNShandle is no longer valid.


The handle is recognized by the PNS but it is not valid for the current notification.

Request problems


The PNS raises an error regarding the format of the notification.

Note: This can happen if either the template provided is malformed, or the result of applying the template to the incoming message results in a malformed notification.


The PNS raises an error regarding the size of the notification.

Note: as above.

Service Bus Explorer

You can also use the Service Bus Explorer tool to help with the debugging process. You can download Service Bus Explorer here. This tool enables you to explore the devices that are currently registered with your notification hub. You can also use Service Bus Explorer to send test notifications. You can perform all these tasks with the Azure SDK and the .NET client library, and also via REST, but this tool makes the debugging process much easier. For a quick introduction to Service Bus Explorer, see this video.

When you start Service Bus Explorer, connect it to your namespace using your ACS connection string, and not your hub connection string (the ones you use in your app and back-end). For example:

Connection String

The following are useful tasks when debugging a solution that uses notification hubs:

  1. Make sure that the device registered correctly with the hub. To do so, you can obtain all the registrations in your hub and check that a registration exists with the correct PNSHandle (for example, ChannelURI, device token, or registrationId), and the correct set of tags. In Service Bus Explorer, select your notification hub on the left, and then query for the registrations using the Registrations button at the bottom. Your code in the client app should provide the registrations. For example:

    Service Bus Explorer
  2. If you have the registration, make sure that when you send a message you get a “success” result (you can see it immediately in Service Bus Explorer without having to wait for the portal dashboard to update). If you receive any other outcome, see this MSDN topic to help understand what happened (most problems here are related to the credentials configuration in the hub and/or in the client app).

    Service Bus Explorer For per-platform descriptions of the outcomes, see the Metrics topic.

  3. If the platform notification service returns success, it means that your notification hub successfully delivered your notification to the platform notification system. If it still does not appear, it is usually due to idiosyncrasies specific to each platform. For example:

    • In iOS, if your app is running (even in the background), it will catch your notification. To make the notification show, you must implement the application:didReceivePushNotification: method in your AppDelegate class. Also, if your json payload is incorrect, APNS will accept the notification but the device will not display anything.

    • In Windows Phone, if your app is in the foreground, toasts will not be displayed.

    • In Android, make sure that your broadcast listener is configured correctly and that the permissions are set in the manifest for the appropriate packages.

Finally, check that you are registering for and sending the same kind of notifications to your notification hub. If you register a template, you must send a template notification. If you register for native notifications, you must send a native notification for the correct platform.

Community Additions

© 2015 Microsoft