how to troubleshoot push notifications not arriving

TL;DR

Push delivery has a long chain (your server, the push provider, the OS, the user's settings) and the break is usually at the user's end: notifications disabled, battery optimization killing the app, or Do Not Disturb. Work the chain from the user inward: settings first, then the device registration, then your side. Checking your server first wastes an hour when the answer is a toggled-off permission.

The query

how to troubleshoot push notifications not arriving

Use this when

• Users report notifications never arrive
• Tickets cluster on one phone brand or OS version
• You are validating notifications after a release
• Some notification types arrive but others do not

Not for

• In-app banners or badges
• Email notification problems
• Writing notification copy
• Choosing a push provider

Steps

1. Confirm the OS-level permission

Have the user check notification permission for the app in system settings. This is the top cause by far, and users often disabled it months ago and forgot. Also check Do Not Disturb and any focus modes.

Expected output: permission confirmed on, or the ticket resolves here.

2. Check battery and background restrictions

Aggressive battery optimization kills apps in the background, which kills their notifications with them. Have the user exempt the app from battery optimization and confirm background activity is allowed.

Expected output: the app can run in the background again.

3. Verify the device is registered

Your system keeps a push registration per device. Check whether the user's current device has a fresh registration. A stale or missing registration means the server is sending to a device that no longer exists.

Expected output: you know if the server side even has a target to send to.

4. Send a test notification

Trigger a test push to that device and watch your provider logs for acceptance or rejection. A rejection names the cause: unregistered device, invalid credentials, throttling.

Expected output: the provider's verdict, in its own words.

5. Check provider configuration

If tests fail for many users at once, check the provider credentials, certificate expiry, and any recent config changes. One expired certificate silences every device at the same time.

Expected output: either a config fix or evidence for engineering.

Template: what to ask

Lets narrow this down, [Name]:

1. Are notifications allowed for [App] in your phone settings?
2. Is Do Not Disturb or a focus mode on?
3. Did you recently reinstall the app or switch phones?
4. Do any notifications arrive, or is it all of them?

Variant phrasings

not getting push notifications

Same playbook. Start with the OS permission in step 1.

push notifications stopped working

"Stopped" means something changed: an OS update, a reinstall, a new phone. Ask what changed.

notifications delayed but eventually arrive

Battery optimization batching delivery. Step 2, exempt the app.

Why it happens

A push notification is a relay race: your server hands to Apple or Google, they hand to the device, the OS hands to the user. Every handoff can silently drop the message, and the OS drops them most aggressively to save battery. The system is designed to fail silently, which is why "it just never arrived" is the whole symptom.

Edge cases

• Multiple devices: the registration may point at an old phone. Deregister stale devices.
• Quiet hours and notification summaries: scheduled summaries can make real-time notifications look broken. They arrived, just batched.
• Enterprise-managed devices: device management profiles can block notifications for entire app categories. The user cannot fix this themselves.
• Test versus production push environments: a device registered in the wrong environment never gets production pushes. Common after app updates that switch environments.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_EpHaLdio1OaRds5MtLxbLg