Prompt
How do I troubleshoot push notifications not delivered to some users?
Latest observation
To troubleshoot push notifications that are not being delivered to some users, work through the problem from the outside in: is the notification being sent, accepted by the push provider, delivered to the device, and shown by the OS/app?
1) Confirm the push is actually being sent
- Check your server logs for the notification request.
- Verify the request payload is created for the affected users.
- Confirm the push job/queue isn’t failing or timing out.
- Make sure the user is included in the target audience/segment.
2) Check provider response
Depending on your provider (FCM, APNs, Web Push, etc.), inspect the response:
- Success: provider accepted the message.
- Invalid token / registration error: device token may be stale.
- Unregistered / NotRegistered: the app was uninstalled or token rotated.
- Rate limited / quota exceeded: messages may be dropped or delayed.
- Payload too large: message rejected.
If you see token errors, remove bad tokens and re-register them.
3) Verify device tokens are current
For affected users:
- Confirm the app recently refreshed and uploaded the latest push token.
- Check whether token registration is happening after reinstall, app restore, or OS updates.
- Invalidate old tokens when a new one is issued.
- If the user changed devices, the old token won’t work.
4) Look at platform-specific issues
iOS
- Confirm APNs certificate/key is valid and not expired.
- Ensure the app has the correct entitlements and push capability.
- Check whether the user has disabled notifications for the app.
- Verify Focus mode, Notification Summary, or Do Not Disturb isn’t suppressing alerts.
- Make sure you’re using the correct APNs environment: sandbox vs production.
Android
- Ensure the app has notification permission on Android 13+.
- Check if battery optimization or OEM settings are restricting background delivery.
- Verify the app is not force-stopped.
- Confirm the FCM configuration is correct and the correct sender/project is used.
Web Push
- Check service worker registration and scope.
- Verify the browser permission is granted.
- Ensure the push subscription is still valid.
- Confirm HTTPS is used and VAPID keys are correct.
5) Validate payload formatting
A payload can be accepted but still not display if malformed.
- Check required fields for your provider.
- Ensure
notificationvsdatapayload usage matches your app behavior. - Confirm title/body/image/sound fields are valid.
- Verify collapse keys, TTL, priority, and topic settings.
6) Check app-side handling
The notification may arrive but not be displayed because the app suppresses it:
- Foreground behavior may require custom handling.
- App code may filter out notifications.
- Notification channels on Android may be disabled or set to low importance.
- Silent/data-only messages may require background processing not currently working.
7) Compare affected vs unaffected users
Look for patterns:
- Specific OS version
- Specific device model
- Certain app version
- Users with old installs
- Region/network differences
- Users who haven’t opened the app recently
This often reveals whether the issue is token refresh, permissions, or app version-specific.
8) Reproduce with a single test user/device
- Send a push to one known-good device and one affected device.
- Compare the token, platform, app version, and provider response.
- Test both foreground and background states.
9) Check logs on device
- iOS: Xcode device logs, APNs-related logs, app logs.
- Android: Logcat and Firebase console diagnostics.
- Web: browser devtools, service worker logs.
10) Use delivery metrics if available
Many providers offer dashboards for:
- Sent
- Accepted
- Delivered
- Opened
- Failed
Use these to see where the drop-off happens.
Common root causes
- Expired or stale device tokens
- User disabled notifications
- Incorrect APNs/FCM configuration
- App permissions missing
- Wrong environment or sender ID
- Payload rejected or malformed
- Battery/background restrictions
- Notification channel disabled
- User uninstalled or reinstalled the app
If you want, I can also give you a step-by-step troubleshooting checklist for iOS, Android, or FCM/APNs specifically.
Brands