Troubleshooting
Fixes for the issues we see most often. Find your symptom below.
Notifications not arriving when the app is in background or killed#
Call setBackgroundHandler({ appId, apiKey }) synchronously in your entry file (index.js), before AppRegistry.registerComponent(). Registering it inside a component or after an await is too late for killed-state delivery.
401 Unauthorized errors#
Pass apiKey to both initialize() and setBackgroundHandler(). Also confirm the key belongs to the same app as the appId. See API Keys.
Push does not work on the iOS Simulator#
The iOS Simulator does not support push notifications. Use a physical device.
Android notifications disappear or never show#
A missing small icon makes Android drop the notification. Add a valid small icon to your app as described in the React Native SDK guide.
Android 13+ shows no notifications#
Android 13 and later need the runtime POST_NOTIFICATIONS permission. Request it, and check the user has not denied it in system settings.
AsyncStorage errors#
The SDK expects @react-native-async-storage/async-storage ^1.23.1. Version 2 is not supported. Also install the SDK's other peer dependencies listed in the install step.
Firebase JSON upload fails#
Upload the Service Account key (...firebase-adminsdk-xxxxx.json), not google-services.json. If fields are reported missing, generate a fresh key. See Firebase Credentials.
Web push not working#
Web push needs a domain with valid SSL. Run the SSL Domain Check from the dashboard. See Plans & Billing and Push Setup.
Sends fail or are limited#
Plans can cap sends. Check My Plan first if a send fails unexpectedly.
A user shows as token expired or unsubscribed#
That device cannot receive pushes. Users get a fresh token the next time they open the app and initialize() runs. See Subscriptions.
iOS delivers nothing at all#
Confirm an APNs key is uploaded to your Firebase project and push capabilities are enabled for the app in Xcode. Then test on a physical device.
Stuck or something unclear? Contact us and we'll help.