All Blog

Why Push Notifications Not Working? Complete Debugging Guide for Developers

10 min read

Apr 2, 2026

Why Push Notifications Not Working? Complete Debugging Guide for Developers cover image - push notifications not working iphone, fcm service required

Push notifications are the lifeline of real-time user engagement — but when they silently fail, they become one of the most frustrating problems in mobile and web development. Whether you are dealing with push notifications not working iPhone scenarios, Android devices swallowing messages in the background, or service workers refusing to display web push alerts, the root cause is rarely obvious.

The challenge is that push notification delivery involves a long chain of moving parts: your backend server, the platform gateway (APNs, FCM, or Web Push), the operating system, OEM-specific battery management, and finally the user's permission settings. A single misconfiguration at any point in this chain can cause notifications to vanish without a trace — and without any error message reaching your dashboard.

This comprehensive debugging guide walks you through every common failure point across iOS, Android, and Web Push, gives you a systematic debugging flowchart, and shows you how to resolve each issue with concrete steps. Whether you are a solo developer shipping your first app or a team managing millions of daily notifications, this guide will save you hours of guesswork.

The Push Notification Delivery Chain: Where Things Break

Before diving into platform-specific fixes, it helps to understand the full delivery pipeline. A push notification must successfully pass through every stage below — and failure at any stage means the user sees nothing:

Your backend server constructs a payload and sends it to the platform push service.
The platform gateway (APNs for iOS, FCM for Android, Web Push protocol for browsers) validates credentials and routes the message.
The device operating system receives the message, checks app permissions, and decides whether to display it.
OEM and user-level settings (battery optimization, Do Not Disturb, notification grouping) may suppress, delay, or silently discard the notification.

A systematic approach — checking each stage in order — is far more efficient than random trial-and-error. The sections below are organized by platform, starting with the most common failure points.

iOS: Push Notifications Not Working on iPhone

When push notifications not working iPhone issues arise, the problem almost always falls into one of four categories: APNs authentication, Xcode entitlements, provisional authorization behavior, or device-level settings.

1. APNs Certificate or Key Misconfiguration

The most common server-side cause of silent push failure on iOS is an APNs authentication problem. Apple supports two methods — certificate-based (.p12) and token-based (.p8) — and each has its own pitfalls.

Certificate-based (.p12) issues:

Expired certificate. APNs SSL certificates expire every 12 months. If your certificate has lapsed, Apple rejects every push request silently. Check the expiration date in Keychain Access or your push provider's dashboard.
Wrong environment. Apple issues separate certificates for Development (sandbox) and Production. Sending a production push with a sandbox certificate — or vice versa — results in a rejected connection. Verify you are using api.push.apple.com for production and api.sandbox.push.apple.com for development.
Bundle ID mismatch. The certificate is scoped to a specific Bundle ID. If your app's Bundle ID does not match the certificate, APNs rejects the payload.

Token-based (.p8) issues:

Incorrect Key ID or Team ID. The JWT you sign must include the correct kid (Key ID) and iss (Team ID) claims. A single typo means every request returns a 403 InvalidProviderToken error.
Clock skew. The JWT includes an iat (issued-at) timestamp. If your server's clock is more than a few minutes off from Apple's servers, the token is rejected. Ensure your server uses NTP time synchronization.
Revoked key. If someone regenerated the APNs key in the Apple Developer Portal, the old .p8 file is invalidated immediately.

Quick fix checklist:

Verify your APNs credentials have not expired or been revoked.
Confirm the Bundle ID in your push payload matches your app's registered Bundle ID.
Test with a direct curl command to APNs to isolate whether the issue is in your backend logic or the push provider.

2. Xcode Entitlements and Capabilities

Even with a perfectly configured server, notifications will never arrive if your Xcode project is missing the required entitlements.

Push Notifications capability not added. In Xcode, go to your target → Signing & Capabilities → click + Capability → add Push Notifications. Without this, iOS will never generate a device token for your app.
Missing aps-environment entitlement. The .entitlements file must contain the aps-environment key set to either development or production. If this key is absent, the app cannot register for remote notifications.
Provisioning profile mismatch. If your provisioning profile was generated before push notifications were enabled on the App ID, it will not include the push entitlement. Regenerate the provisioning profile in the Apple Developer Portal and re-download it in Xcode.

Debugging tip: Run your app on a physical device (not the Simulator — push notifications do not work on the iOS Simulator) and check the console output for didRegisterForRemoteNotificationsWithDeviceToken or didFailToRegisterForRemoteNotificationsWithError. If you see the failure callback, the error message will tell you exactly what is wrong.

3. Provisional and Ephemeral Authorization

Starting with iOS 12, Apple introduced provisional authorization, which allows apps to send notifications to the Notification Center without an explicit user opt-in — but these notifications are delivered quietly (no sound, no banner, no Lock Screen alert). If your team enabled provisional auth and is wondering why users are not reacting to notifications, this is likely the cause.

Similarly, iOS 16+ ephemeral notifications for App Clips expire after a set period. If your push infrastructure is targeting an App Clip token that has expired, notifications will silently fail.

4. Device-Level Settings and Focus Mode

Sometimes the server and app are perfectly configured, but the user's device settings suppress the notification:

Notifications toggled off for your app in Settings → Notifications.
Focus Mode or Do Not Disturb active, filtering out your app's alerts.
Low Power Mode can delay background fetch and push processing.
Notification Summary (iOS 15+) batches non-time-sensitive notifications and delivers them at scheduled times rather than immediately.

Android: FCM Configuration and OEM Battery Restrictions

Android push issues tend to be split between FCM setup errors and aggressive OEM battery management — the latter being especially difficult to debug because behavior varies across manufacturers.

1. FCM Service Configuration

FCM service required — Firebase Cloud Messaging is the mandatory gateway for push notifications on Android. Without a correctly configured FCM setup, no notification reaches the device.

Common FCM issues include:

Missing google-services.json. This file must be placed in your app's app/ directory and must match the Firebase project linked to your app's package name. A mismatched package name means the device never obtains a valid FCM registration token.
Server key vs. v1 API credentials. Google has deprecated the legacy server key in favor of the FCM v1 API, which uses OAuth 2.0 service account credentials. If your backend still sends requests to fcm.googleapis.com/fcm/send with a server key, migration is overdue — and new Firebase projects no longer generate legacy server keys at all.
Invalid or stale registration tokens. FCM tokens can change when the user reinstalls the app, clears app data, or restores to a new device. Your backend must handle the messaging/registration-token-not-registered error by removing stale tokens from your database.
Topic subscription failures. If you use FCM topic messaging, ensure the client successfully subscribes before you send to that topic. Race conditions during app startup can cause missed subscriptions.

2. OEM Battery Restrictions: Xiaomi, OPPO, vivo, and More

This is the single biggest source of "it works on my Pixel but not on real user devices" problems. Chinese OEM manufacturers ship aggressive battery optimization and app-kill policies that go far beyond stock Android:

Xiaomi (MIUI / HyperOS):

MIUI aggressively kills background processes. Users must manually enable Autostart for your app (Settings → Apps → Manage apps → [Your App] → Autostart).
The Battery saver setting can prevent FCM from waking your app. Users need to set your app's battery optimization to "No restrictions."
MIUI may also restrict background data access, which prevents the persistent FCM connection from staying alive.

OPPO (ColorOS):

ColorOS has a built-in App Quick Freeze feature that hibernates apps after a period of inactivity. Frozen apps do not receive push notifications.
Users need to add your app to the "Allow background running" list in battery settings and disable "Auto-optimize" for your app.

vivo (Funtouch OS / OriginOS):

vivo devices have an extremely aggressive background app management system. Apps not on the whitelist are killed within minutes of being backgrounded.
High-priority FCM messages (priority = "high") can sometimes break through, but regular-priority messages are almost always delayed or dropped on vivo devices.

Samsung (One UI):

Sleeping apps and Deep sleeping apps lists will prevent your app from receiving push notifications. Users must remove your app from these lists.
Adaptive Battery can also interfere, though Samsung is less aggressive than Chinese OEMs.

What you can do as a developer:

Use high-priority FCM messages for time-sensitive notifications (but do not abuse this — Google throttles apps that overuse high priority).
Detect the device manufacturer at runtime and show users a one-time guide for enabling the correct battery/autostart settings. Libraries like AutoStarter can help launch the correct settings page on each OEM.
Implement a push delivery confirmation mechanism: when the device receives a notification, send an acknowledgment back to your server so you can track actual delivery rates by device manufacturer.

3. Notification Channels (Android 8.0+)

Starting with Android Oreo, every notification must be assigned to a Notification Channel. If your app targets API 26+ but does not create a channel before posting a notification, the system silently discards it. Additionally, users can disable individual channels without turning off all notifications for your app — check your channel settings in the system notification preferences.

Web Push: Service Worker and VAPID Issues

Web push notifications rely on a service worker and the Web Push protocol with VAPID authentication. When web push stops working, the problem is usually in one of these areas:

1. Service Worker Not Registered or Out of Scope

The service worker file must be served from the root scope of your domain (or the scope must be explicitly set). A service worker at /subfolder/sw.js will not intercept push events for pages outside /subfolder/.
If the service worker fails to install (syntax error, failed fetch during install), push subscriptions will not work. Check the browser DevTools → Application → Service Workers for error messages.
After updating your service worker, ensure the new version activates. A stuck "waiting" worker will not handle push events.

2. VAPID Key Mismatch

Web push requires a VAPID (Voluntary Application Server Identification) key pair. The public key used when subscribing the user in the browser must match the private key used on your server when sending the push. A mismatch results in a 401 Unauthorized response from the push service.

3. Browser and OS-Level Permissions

The user must grant notification permission (Notification.permission === 'granted'). If the user previously denied permission, the browser blocks the permission prompt from appearing again — the user must manually re-enable it in browser settings.
macOS Ventura+ added system-level notification preferences for browsers. Even if the user granted permission in the browser, macOS may suppress the notification if browser notifications are disabled in System Settings → Notifications.
Windows Focus Assist and macOS Focus Mode can suppress browser notifications system-wide.

4. Subscription Expiration

Web push subscriptions can expire. The PushSubscription object includes an expirationTime property (often null, meaning no fixed expiration), but the push service can invalidate a subscription at any time. Your server must handle 410 Gone responses by removing the expired subscription and prompting the user to re-subscribe.

Universal Debugging Flowchart

Use this systematic flowchart to isolate push notification failures on any platform:

START: Notification not received
│
├─ Step 1: Can the device obtain a push token?
│   ├─ NO → Check entitlements (iOS), google-services.json (Android), service worker (Web)
│   └─ YES ↓
│
├─ Step 2: Does the server send the push successfully (2xx response)?
│   ├─ NO → Check auth credentials (APNs key/cert, FCM service account, VAPID keys)
│   └─ YES ↓
│
├─ Step 3: Is the push token still valid?
│   ├─ NO → Token expired or app reinstalled — refresh token on server
│   └─ YES ↓
│
├─ Step 4: Does a test push from the platform console arrive?
│   ├─ (iOS: APNs push tool in Xcode / macOS console)
│   ├─ (Android: Firebase Console → Cloud Messaging → Send test message)
│   ├─ (Web: Browser DevTools → Application → Service Workers → Push)
│   ├─ NO → Device-level issue (permissions, battery optimization, Focus Mode)
│   └─ YES → Issue is in your server-side targeting, payload construction, or timing
│
└─ Step 5: Check OEM-specific battery/background restrictions (Android)
    └─ Guide user to whitelist your app

How Tencent Push Simplifies Debugging

Diagnosing push failures across iOS, Android, and Web manually is time-consuming — especially at scale. Tencent Push Notification Service includes built-in diagnostic tools that eliminate much of this guesswork:

Push Troubleshooting Tool — Enter a device token and Tencent Push traces the entire delivery path, showing you exactly where the notification was dropped (server rejection, token invalid, device offline, OEM killed process).
Device-level delivery tracking — Real-time dashboards show per-device delivery, display, and click status, so you can immediately spot manufacturer-specific drop-off patterns (e.g., vivo devices showing 40% lower delivery than Samsung).
Vendor channel integration — Tencent Push maintains official integrations with Xiaomi Push (MiPush), OPPO Push, vivo Push, Huawei Push Kit, and Honor Push. Instead of wrestling with each OEM's proprietary SDK yourself, Tencent Push aggregates all vendor channels into a single API, automatically routing messages through the OEM-native channel when the FCM channel is unreliable.
Intelligent retry and channel selection — When FCM delivery fails (common on Chinese OEM devices), Tencent Push automatically falls back to the OEM's native push channel, dramatically improving delivery rates.

If you are spending more time debugging push infrastructure than building features, a managed push service with built-in observability can be a significant force multiplier.

Best Practices to Prevent Push Failures

Monitor token freshness. Implement a server-side job that periodically validates push tokens and removes stale ones. Both APNs and FCM provide feedback mechanisms for invalid tokens.
Use high-priority sparingly. Reserve high-priority delivery for genuinely time-sensitive notifications (incoming calls, security alerts). Overuse triggers platform-level throttling.
Test on real OEM devices. Emulators and Pixel devices do not reproduce OEM-specific battery kill behavior. Maintain a test device lab that includes Xiaomi, OPPO, vivo, and Samsung devices.
Implement delivery receipts. Have your app send an acknowledgment back to your server when a notification is received and displayed. This gives you ground-truth delivery data beyond what platform dashboards report.
Handle permission changes gracefully. Users can revoke notification permission at any time. Check permission status on each app launch and update your server-side records accordingly.
Set up alerting on delivery rate drops. A sudden decline in push delivery rates often indicates a credential expiration, API deprecation, or OEM policy change. Automated alerts let you catch these issues before users report them.

Frequently Asked Questions

Why are push notifications not working on my iPhone after an iOS update?

Major iOS updates can reset notification permissions, invalidate provisioning profiles, or introduce new permission requirements. After updating, check Settings → Notifications to confirm your app still has permission enabled. Developers should also verify that their APNs credentials and Xcode entitlements are compatible with the latest iOS version.

What does "FCM service required" mean on Android?

This message typically means the device lacks Google Play Services, which is required for Firebase Cloud Messaging. It is common on Huawei devices that ship without Google Mobile Services (GMS). To reach these devices, you need an alternative push channel — either Huawei Push Kit directly or a service like Tencent Push that integrates multiple vendor channels.

Why do push notifications work on Samsung but not on Xiaomi or OPPO?

Chinese OEM manufacturers implement aggressive battery optimization that kills background app processes — including the FCM connection. Samsung's battery management is comparatively lenient. On Xiaomi, users must enable Autostart and disable battery optimization for your app. On OPPO, the app must be added to the background running whitelist. As a developer, detect the OEM at runtime and guide users through the necessary settings.

How do I test push notifications during development?

For iOS, use the push notification testing tool built into Xcode or send a test payload via curl to the APNs sandbox endpoint. For Android, use the Firebase Console's test message feature or send a request to the FCM v1 API with your test device's registration token. For Web, use the browser DevTools Application panel to simulate a push event on your service worker.

Can push notifications be delayed rather than completely lost?

Yes. Several factors cause notification delays rather than total failure: Android Doze mode batches notifications when the device is idle, iOS Notification Summary defers non-time-sensitive alerts to scheduled times, and network connectivity issues can delay delivery until the device reconnects. If users report inconsistent timing rather than missing notifications, these batching and deferral mechanisms are the most likely cause.

Why did push notifications stop working after I changed my server infrastructure?

Migrating servers, changing cloud providers, or updating your backend framework can inadvertently break push delivery. Common causes include: the new server not having the APNs .p8 key or FCM service account JSON deployed, firewall rules blocking outbound connections to APNs (port 443) or FCM endpoints, clock synchronization issues affecting JWT token generation, and environment variables for push credentials not being set in the new deployment.

How can I improve push notification delivery rates on Android in China?

In mainland China, Google Play Services (and therefore FCM) is largely inaccessible. To achieve reliable delivery, you must integrate with each OEM's native push channel — Xiaomi MiPush, Huawei Push Kit, OPPO Push, vivo Push, and others. Managing these integrations individually is complex, which is why many teams use an aggregation service that handles vendor channel routing automatically.

Conclusion

Push notification debugging is inherently cross-disciplinary — it spans server-side authentication, platform-specific SDKs, operating system permission models, and OEM-level battery policies. The key to solving push notifications not working issues quickly is a systematic approach: verify the token, verify the server response, verify the platform credentials, and then investigate device-level settings.

For iOS, focus on APNs credentials and Xcode entitlements first. For Android, start with FCM configuration and then investigate OEM-specific battery restrictions — especially on Xiaomi, OPPO, and vivo devices where FCM service required errors and background process kills are the most common culprits. For Web, check your service worker registration and VAPID key alignment.

And if you are managing push at scale across all three platforms, investing in a push service with built-in diagnostics and vendor channel aggregation will save your team significant engineering time and dramatically improve your delivery rates.