This page covers common issues, error codes, and frequently asked questions related to Countly Push Notifications. For the full setup guide covering server-side configuration and SDK integration, see our integration guide:
Troubleshooting
Apple Push Notifications Service certificate cannot be uploaded
In some cases, as you start to upload your APNS certificate, you may see popups, similar to the one displayed below:
Countly validates a certificate at the time of upload by establishing a connection and sending a dummy message to a dummy user token. Depending on what happens, Countly responds with 3 main types of errors:
1. APN production certificate is invalid. Please check your passphrase. (Couldn't read certificate)
Countly couldn't read your certificate; no test connection has yet been completed. This error means that either your certificate has been generated incorrectly (use Keychain Access or openssl to check) or you may have specified the incorrect passphrase. Export your certificate from Keychain Access again if the error persists.
2. APN production certificate is invalid. Please check your passphrase. (Countly now requires universal HTTP/2 certificates. Please see our guide here.)
Countly supports only universal certificates (Production and Sandbox in the Apple Developer Portal). Only Production or Sandbox certificates are no longer needed for iOS apps, as universal certificates work for both sandbox and production environments.
We strongly recommend using the Auth Key (.p8) approach instead of certificates. Auth Keys do not expire, work for both sandbox and production environments, and are simpler to manage. See the Push Notifications Integration Guide for setup instructions.
3. APN production certificate is invalid. Please check your passphrase. (Certificate rejected by APN. Possibly wrong private key if you have more than one.)
This error means that your certificate has been rejected by Apple several times. Most likely your certificate is invalid because it is signed with the incorrect private key. To be sure about the validity of your certificate, regenerate it from a computer which will use it to create Ad Hoc or App Store builds (since you can submit it to Apple, it would seem that you have all the provisioning profiles and private keys installed; sometimes Xcode would regenerate some for you in the process).
No push-enabled users appear in the Dashboard
Possible causes: The SDK is not initialized with push enabled - ensure you have set the push token type (iOS) or notification channel (Android) in your config before calling init. On iOS, verify that the Push Notifications capability is added in Xcode and that the user has accepted the notification permission prompt. Also confirm the app is running on a physical device, not a simulator.
If using consent management, ensure that push consent has been granted.
A device doesn't receive a notification
Please ensure that the device count on the message creation screen includes the device with the issue. If it doesn't, ensure that the device supports push notifications (has Play Services installed for Android, and has authorized push notifications when the app is first opened for iOS).
To verify that the device is sending push tokens to the Countly Server, enable SDK logging and ensure that requests containing token_session are submitted during the app session. See the Android SDK guide and iOS SDK guide for details on logging.
Some users don't receive push notifications
If you see on the dashboard that some of your users don't receive push notifications, then either they have uninstalled your application, or their device tokens are invalid. Under the Messaging dashboard, you will see how many invalid push notification tokens there are per each push notification sent.
Push providers can also invalidate device tokens when: the user reinstalls the app, the device is restored from a backup, or the provider rotates the token. This is normal behavior. Countly automatically removes expired tokens, and the user will receive a new token the next time they open the app.
BadDeviceToken (APN)
The device token sent by the SDK was rejected by APN as invalid. This typically means the token was generated for a different environment or is corrupt. Verify that your APN credentials (Auth Key or certificate) in the Countly Dashboard match the app you are targeting, and that the Bundle ID is correct.
InvalidProviderToken (APN)
One or more of your APN Auth Key credentials are incorrect. Double-check the Key ID, Team ID, and Bundle ID values in the Countly Dashboard. Ensure the .p8 file you uploaded corresponds to the correct key.
DeviceTokenNotForTopic (APN)
The APN certificate does not correspond to the Bundle ID of your application. If using certificate-based auth, make sure you generated the push certificate for the correct App ID / Bundle ID. If using Auth Key, verify the Bundle ID field in the Dashboard matches your app's actual Bundle ID.
I receive error codes after a notification is sent
Depending on the push service performance, uptime, and reliability, you may get several errors as you send notifications. All errors you see in a message popup when it is sent have valid explanations. You can consult the APN errors and FCM errors links for more details. If you see errors after sending a notification, check the following:
- Check that your credentials (APN Auth Key or certificate for iOS, Service Account JSON for FCM, App ID and App Secret for HMS) are made for the app to which you are sending the message. Ensure the Bundle ID of your iOS app and the package name of your Android app match the credentials configured in the Countly Dashboard.
- For iOS-specific cases, check that your app has correct entitlements and that the Push Notifications capability is enabled in Xcode.
- For Android-specific cases, check that you aren't using other FCM-enabled SDKs in your app. They might begin competing for tokens with the Countly Android SDK, resulting in inconsistent behavior.
MismatchSenderId (FCM)
The Sender ID used to register the device does not match the one from the credentials uploaded to Countly. This typically happens when your app includes another Firebase SDK that competes for the FCM token. Ensure both SDKs use the same Firebase project, or override token registration so they share the same token.
InvalidPackageName (FCM)
Your app's package name does not match the package name registered in the Firebase Console. Navigate to your Firebase project settings and verify that the Android package name matches your app's applicationId in build.gradle.
NoConnection
The Countly Server was unable to connect to the push notification provider (APN, FCM, or HMS). Verify that your server has outbound internet access to the following endpoints:
| Provider | Endpoint |
|---|---|
| APN |
api.push.apple.com:443 (production)api.development.push.apple.com:443 (sandbox)Port 2197 also supported as fallback |
| FCM |
fcm.googleapis.com:443accounts.google.com:443
|
| HMS |
push-api.cloud.huawei.com:443oauth-login.cloud.huawei.com:443 (authentication)
|
If your server uses a proxy, check that the proxy is running and properly configured.
ECONNRESET / Connection refused errors
If you see ECONNRESET, ECONNREFUSED, or similar connection errors when sending push notifications, your server's firewall or network configuration is likely blocking outbound connections to push notification providers. You need to allow outbound traffic on the following ports and endpoints:
Outgoing port 443 (HTTPS):
-
api.push.apple.com(APN production) -
api.development.push.apple.com(APN development/sandbox) -
fcm.googleapis.com(FCM) -
accounts.google.com(FCM authentication) -
push-api.cloud.huawei.com(HMS Push) -
oauth-login.cloud.huawei.com(HMS authentication)
Outgoing port 2197 (fallback for APNs):
api.push.apple.comapi.development.push.apple.com
Apple uses port 443 as the primary port for APNs, but also supports port 2197 as a fallback. If your firewall restricts traffic on port 443 for Apple endpoints, ensure port 2197 is open as an alternative.
Contact your system administrator or hosting provider to ensure these outbound connections are permitted. If your Countly Server uses a proxy, also verify the proxy settings under Management > Settings > Push Notifications.
After resolving network/firewall issues, do a hard refresh (Ctrl+Shift+R / Cmd+Shift+R) on the Countly Dashboard settings page before uploading your push credentials. Similarly, do a hard refresh before creating a new push notification to ensure the Dashboard reflects the latest server state.
ExpiredCreds - push credentials have expired
Your push notification credentials have expired. If using APN certificates (.p12), they expire after one year and must be regenerated and re-uploaded. This is one reason Auth Keys (.p8) are recommended - they do not expire. For FCM, Service Account JSON files do not expire but can be revoked; generate a new one from the Firebase Console if needed.
Expired Tokens
Countly cannot send a push notification for a device if that token is expired. APN, FCM, or HMS can issue a new device token for a variety of reasons:
- User installs your app on a new device
- User restores device from a backup
- User reinstalls the operating system
- User clears the application data
- Other system-defined events
When you see one or more devices with a token-expired notification after a push notification has been sent, the reasons for the notification are stated above.
Notification received but not displayed (Android)
On Android 8.0+, notifications require a notification channel. Ensure you have created a notification channel with CountlyPush.CHANNEL_ID during SDK initialization. Also verify that the user has not disabled notifications for your app in their device settings.
Notifications sent with status "Sending | Failed" or "Sent | Failed"
Partial failure means some notifications were delivered while others failed. Common causes include expired tokens, invalid credentials for a subset of devices, or provider-side rate limiting. Click the three-dot ellipsis menu on the notification row in the Dashboard to view error details, and use the Resend Failed Notifications option to retry delivery to affected users.
Frequently Asked Questions
Can I send push notifications to both iOS and Android from a single Countly app?
Yes. A single Countly application can have credentials for all three providers (APN, FCM, HMS) configured simultaneously. When composing a push notification, you can target multiple platforms at once.
Does Countly push notifications have an API?
Yes, it's possible to send push notifications programmatically. Refer to the Push Notifications documentation for API endpoints, parameters, and examples.
Do push notifications work on simulators/emulators?
iOS: Push notifications do not work on the iOS Simulator. You must use a physical device. Android: FCM push can work on emulators that include Google Play Services. HMS requires a Huawei device or HMS-enabled emulator.
What happens when a device is offline?
If a device is offline when a notification is sent, the push provider (APN/FCM/HMS) queues the message and delivers it when the device comes back online, subject to the provider's time-to-live (TTL) policies.
Where can I host my images or videos?
All images and videos should be hosted on a site and each device will retrieve those images and videos before showing the notification to your users. Note that Apple requires storing those images on a secure URL (which should start with HTTPS).
How can I enter the required information for my app to send a push notification?
In the Countly Dashboard, navigate to Management > Applications, select your app, and scroll to the Push Notifications section. You will see fields for each provider (APN, FCM, HMS). For step-by-step instructions, see the Push Notifications Integration Guide.
What are general industry standards for opening push notifications?
In our investigations, opening rate is between 10-60% for most applications. You can greatly increase this number by educating your app users before asking for a push receipt request - so that they can know they'll benefit from your app by allowing to get push notifications.