Debugging Notification Hubs

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 takes a bit of work to set up your notification hub with the correct push credentials, to register your device app with the platform notification system and with the hub, and finally, to update your back-end to send notifications. Because of the complexity of such an architecture, there is a chance of a mistake or failure somewhere along the line that results in notifications not being received on the device. Fortunately, there are several tools that are helpful when debugging your push notification configuration.

  • Azure Management Portal

  • Visual Studio Server Explorer

  • Service Bus Explorer

Azure Management Portal

You can use the Azure Management Portal to both monitor the status of both notifications and registrations, and you can send test notifications. You can access this capability in the Debug tab of your notification hub, as shown in the following:


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.

Visual Studio Server Explorer

The Server Explorer in Visual Studio connects to your Microsoft Azure subscription to enable you to work with your Azure services right from the Visual Studio IDE. When connected, you can perform some limited testing and debugging of your notification hubs. Debugging in Visual Studio is particularly convenient when you are testing your app in Visual Studio. From Visual Studio, you can review existing push notification registrations for a given notification hub. You can also test your notification hubs configuration by sending test messages to registered devices.

To diagnose a notification hub in Visual Studio, expand the Notification Hubs node in the Server Explorer under Azure, then right-click the hub name and click Diagnose.


To navigate directly to the Azure Management Portal from Visual Studio, right-click the hub name in Server Explorer, then click Open in Management Portal.

The following is the Device Registrations diagnostic tab, which shows existing registrations:

Existing notification hub registrations

When you have a large number of registrations, you can both filter the list based on tags and sort the list by column. You can also edit the tags of an existing registration by selecting an existing registration and then clicking the edit tag icon.

The following is the Test Send diagnostic tab, which lets you send a test message to an existing registration:

Visual Studio Notification Hubs test send

You can either send a notification to client registrations at random (broadcast) or only to registrations with a specific tag. When using this test functionality, Visual Studio guarantees that no more than 10 clients receive test notifications, and results of the test are displayed in the Message Result table. This is the same behavior as setting the EnableTestSend to true on the NotificationHubClient API.

When you choose a message type, a test message is generated with the correct format for the selected platform and push notification type.

Additional information about the notification hub, including configuration status, connection string information, and registration time-to-live (TTL), is displayed in the Properties window. The TTL is displayed in the serialized day and hour format of PxxDTyyH, where xx is days and yy is hours, with the default 90-day registration being P90D.

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.

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.