Debugging Ably Push Notifications

If you aren’t receiving the expected push notifications on your device, it could be due to issues with Ably, FCM (Firebase Cloud Messaging), APNs (Apple Push Notification service), or your device's configuration. Here’s how you can troubleshoot the problem:

Verify device registration with Ably

First, confirm that your device is registered with Ably

  • Go to the Ably dashboardNotifications tabDevice inspector.

  • Locate your device using  deviceId or clientId

Device states

  • If you cant see that the device is registered, enable verbose logs and go through the push registration process, this should show requests to the Ably push API . If you need help interpreting these logs please contact support

Check for errors

Any errors with Ably publishing push notifications to the relevant push provider i.e FCM or APNS will be recorded in the meta channel with the name [meta]log:push

  • Check for any push related errors in this channel via the application wide events section in the Ably dev console or you can subscribe to the [meta]log:push channel instead. 
  • Check the meta channel history for historic push errors via the history API
  • Check the stats within the Notifications section on your Ably app dashboard to understand if the push notifications are successfully was delivered at all from Ably

From any errors there you should see an FCM or APNS reason why the notification failed. See specific errors for platform specific errors and what they may mean 

If there are no errors it means the notification was sent to the push provider as expected.

Specific errors

APNs

BadDeviceToken - In this case, the device token is invalid. Make sure the environment for push notifications on the app (Runner.entitlements) matches the environment set in Ably dashboards push notification tab.
When running a debug application, the sandbox / development APNs server is used. Make sure to use an application with Use APNS sandbox environment? enabled in the Ably dashboard (push notification tab). Changing the aps-environment value in the .entitlements file to production does not make the debug application use the production APNs server.

DeviceTokenNotForTopic - In this case the error is returned from APNS when the bundle Id of a token or certificate uploaded to Ably does not match the bundle id in you Xcode project settings

no valid topic header for APNS - In this case the error is returned from APNS when the APNS push configuration added to your Ably app has an empty value for the Topic Header field. Generally if you upload an APNS certificate, the APNS topic will be extracted from the certificate but if using token authentication there is an additional field to add the topic header manually

FCM

FcmTransport not configured -  In this case the json file uploaded is not in the expected format of a service account key file. Please check the steps required on the configuring android documentation.

403 Forbidden - In this case it could mean that the firebase cloud messaging API is not enabled in your FCM project. Check that the Firebase cloud messaging API (V1) is enabled under the FCM projects cloud messaging tab.
It could also mean the service account used does not have the correct permissions e.g Permission 'cloudmessaging.messages.create' denied on resource

404 NOT_FOUND (UNREGISTERED) - In this case the device has been unregistered for push with FCM. This can happen if the app is uninstalled on the device and therefore deactivate has never been called and the registration remains on Ably. You can check a list of registered devices via the REST API or push admin from an Ably SDK

404 Unable to get device; not found - In this case the device is most probably in a failed state and can be from sending a push to a device that is already unregistered (as above). You can check the status of the specific device id via the push admin API 

400 Bad Request ( INVALID_ARGUMENT ) - In this case it is related to the push payload being sent to FCM. In the HTTP v1 API payloads such as nested JSON or integer values are not supported and will need to be strings.

DeprecatedApi - In this case this is related to the deprecation of the legacy google FCM API. You will need to create a service account key to upload the JSON to the ably dashboard so the push notifications are sent to the HTTP v1 API 

Web push

Failed to register service worker - Registration failed - A subscription with a different applicationServerKey (or gcm_sender_id) already exists; to change the applicationServerKey, unsubscribe then resubscribe 

Note: This error will be seen in the browser when the Ably SDK tries to register the service worker

In this case the browser has been registered with another vapid key potentially from previously using a 3rd party SDK to implement web push. To resolve you can:

Go to the general browser settings and remove the permission from there. For example in Chrome go to Preferences -> Privacy and security -> Content settings -> Notifications and click "Remove" near the permission.