Push Notifications Not Received: Diagnosis Guide

Users get one push notification and decide your app is worth opening, or they do not get it and assume your app is broken. Non-delivery is common and has many causes — from the OS's battery optimizati

Users get one push notification and decide your app is worth opening, or they do not get it and assume your app is broken. Non-delivery is common and has many causes — from the OS's battery optimization to token churn to plain old carrier issues. This guide is the diagnostic ladder.

Symptoms

• User subscribed to notifications, no notifications arrive
• Some notifications arrive, others do not
• Notifications arrive delayed (hours)
• Notifications arrive but bring user to wrong screen
• Silent notifications work but visible ones do not (or vice versa)

Diagnostic ladder

1. Is the user subscribed?

OS settings → App → Notifications. Are they enabled?

2. Does the app have a FCM / APNs token?

Client-side log: did onNewToken fire and post to server?

3. Is the token registered server-side?

Server log: is the current token on file for this user account?

4. Is the token valid with FCM / APNs?

Test-send to the token. Does FCM / APNs accept or reject?

5. Is the backend actually sending?

Check send logs. Did a notification send job fire for this user?

6. Is the user's device online?

Push delivery requires connectivity. No network = no push.

7. Is the OS throttling?

Android 12+ restricts notifications from background-restricted apps. Battery saver can delay.

8. Is the app in Stopped state (Android)?

After Force Stop from Settings, Android 3.1+ will not deliver broadcasts until next manual app open.

9. Is the user on a Chinese / fork OS?

MIUI, EMUI, ColorOS, Oxygen OS often have aggressive battery optimization. Apps need explicit user permission to run in background.

10. Is the notification content misformatted?

Malformed payload → FCM rejects silently, user sees nothing.

11. Is it a data-only notification without wake?

priority: normal, no notification payload, device in doze. Will not wake.

12. Is the user's carrier blocking?

Rare but exists. Specific carriers block specific push servers.

Common causes

FCM token churn

Token changes when app updates, OS updates, uninstall/reinstall, or FCM rotates. Server sends to old token → rejected by FCM → user misses notification.

Fix: Client calls onNewToken updates server. Server prunes invalid tokens on FCM's "unregistered" response.

APNs production vs sandbox certificates

Debug build has sandbox APNs certificate. Production has production. Mixing them = silent failure.

Fix: Correct environment per build. Monitor certificate expiry.

Notification permission missing (Android 13+)

Android 13+ requires runtime POST_NOTIFICATIONS permission. Without it, post() silently does nothing.

Fix: Request permission at launch or feature-use. Respect denial.

Notification channels (Android 8+)

Channel disabled by user. App posts to disabled channel → user does not see.

Fix: Create channels with appropriate importance. Detect channel-disabled state; prompt user if critical.

Notification throttled by OS

Aggressive battery optimizer (Doze, App Standby, OEM aggressive mode) batches / delays pushes.

Fix: Set priority correctly. Use high-priority for urgent notifications. Accept that background-restricted apps deliver late.

Silent notifications not waking app

Data-only push without notification block does not wake the app; no visible notification.

Fix: Use notification payload for visible notifications. Data-only for sync.

Grouping collapses notifications

Multiple notifications with same tag → grouped, only latest visible. Earlier ones look missing.

Fix: Unique tags per notification. Or intentional grouping with clear summary.

DND / Focus mode

User's system Do Not Disturb filters non-urgent. User thinks app is broken.

Fix: Check interruption settings. Clearly labeled "urgent" channels only for actual urgency.

Diagnosis

Client-side

• Log: token received, posted to server, last push received timestamp
• Manually trigger send to self: does it arrive?

Server-side

• Send succeeded per FCM / APNs response
• Token vs user mapping correct
• Delivery metrics per platform

Device

• Settings → Notifications → App: enabled?
• Settings → Battery → App: not restricted?
• No "unusual battery use" flag

Test delivery

• Firebase Console → Cloud Messaging → send test to specific token
• If works: backend issue
• If does not work: token / OS issue

Fix patterns

• Token sync on every launch. Cheap call; eliminates stale token.
• Per-user delivery log. Track expected vs received.
• Alerting. Deliveries dropped > threshold → page.
• Retry logic. First send fails → retry with backoff, alternate pathway if feasible.

How SUSA tests notifications

SUSA can simulate push arrival via intent injection, testing the in-app handling of notifications. It cannot test FCM / APNs delivery end-to-end (out of scope).

For end-to-end, pair SUSA with a dedicated push testing harness that sends real notifications to test devices and verifies receipt.

susatest-agent test myapp.apk --inject-push '{"title":"Test","body":"...","deeplink":"/inbox/123"}'

Prevention

• Launch-time token sync
• Delivery metrics dashboard per platform, per version
• Monitor alert on sudden drop in delivery rate
• Regression test on permission flows per release

Notifications are the #1 engagement lever. Lose them, lose retention.