Skip to main content
If you are having issues with your website, see the Web Push Troubleshooting guide.

​
Troubleshooting steps

​
Review setup instructions and update the SDK

We frequently release updates with bug fixes, improvements, and support for the latest operating system changes. Ensure you are using the latest SDK version and have followed the setup instructions.

Mobile SDK setup

Setup instructions designed to help prevent common issues and test the integration.

​
Check common troubleshooting guides

Notifications not shown or delayed

Push notifications are not appearing on the device or are delayed.

Notification images not showing

Images are not appearing in the expanded notification view.

Notification CTR

Low or no clicks on notifications.

Duplicated notifications

Notifications are appearing multiple times on the device.

In-app message troubleshooting

In-app messages are not displaying or behaving as expected.

​
Check your app for common issues

​
OneSignal methods that block push from showing

Check your app for optOut() like OneSignal.User.pushSubscription.optOut() or if you set enabled: false via our REST APIs. This sets the push subscription status to unsubscribed. See Mobile SDK reference for more details. If you have the app open while the push is being sent, you may be preventing the push from showing via the preventDefault() method. This is usually set in the Foreground Event Listener or Android Notification Service Extension.

​
Firebase Messaging or other SDK conflicts

If your app also includes the Firebase Messaging SDK or other push notification SDKs, verify it is not intercepting messages before OneSignal can process them. This issue commonly occurs when:
  • Notifications show as Delivered in OneSignal but never appear on the device.
  • The app includes both OneSignal and firebase_messaging (or a custom FirebaseMessagingService).
  • Push works when Firebase Messaging is removed, but fails when both SDKs are present.
  1. Check your AndroidManifest.xml for legacy Firebase receivers such as com.google.firebase.iid.FirebaseInstanceIdReceiver and remove/conditionally exclude them if OneSignal is responsible for push delivery.
  2. Check for custom FirebaseMessagingService implementations (or libraries such as firebase_messaging in Flutter) that override onMessageReceived. If another service fully processes or suppresses messages, it may consume the FCM payload before OneSignal can display the notification.
  3. Avoid calling Firebase token management APIs such as: FirebaseMessaging.getToken() or FirebaseMessaging.deleteToken().
If OneSignal is responsible for push delivery, it should be the only SDK managing the push token lifecycle. Fetching or managing the FCM token directly can lead to token ownership conflicts and inconsistent delivery behavior. If you need the device push token for other systems, read it from OneSignal (for example, User.pushSubscription.token) and listen for subscription/token changes using the SDK’s observer APIs.

​
Test an example project your SDK

Check if the issue is reproducible using the example project maintained by our engineering team for each SDK.

​
Check the error logs

Gather log data before diagnosing further:
  • Follow the guide on capturing a debug log.
  • Look for errors, warnings, or deprecation notices that could explain the behavior.

Capturing a debug log

How to enable verbose logging and capture SDK output for troubleshooting.

​
Contact support

If you are still experiencing the issue, contact support@onesignal.com with:
  • Your OneSignal App ID
  • Your External ID and/or Subscription ID of the affected device
  • The notification ID or a link to the notification in the dashboard (if applicable)
  • A debug log from the device reproducing the issue

​
Common errors

​
APNS Delegate never fired

Errors like “APNS Delegate Never Fired” and “APNS 3000” are timeout messages from Apple indicating that the device could not connect to Apple’s APNS servers. This is most common when:
  • Testing on APNS development environments
  • Using multiple push notification dependencies or native iOS push APIs alongside OneSignal
  • A temporary connectivity issue — this often self-resolves the next time the user starts a new session (app in background for 30+ seconds, then reopened)
Steps to resolve:
  1. Remove any other push notification dependencies or native iOS push APIs and use only OneSignal. Once the error resolves, you can re-add the other code. Contact support@onesignal.com for best practices on coexistence.
  2. Check the debug log from the device for more details.
  3. If the error persists, contact support.

​
App not opening when force-closed and clicking a notification

Make sure you are not testing on a Debug build. For example, on Flutter Apps, you can either:
  • Use a release build via Flutter e.g. flutter run --release (requires a physical device)
  • Update the Xcode scheme to be Release not Debug

Mobile SDK setup

Setup instructions for all supported mobile and cross-platform SDKs.

Capturing a debug log

How to capture SDK logs for troubleshooting.

Web Push troubleshooting

Troubleshoot web push notification issues.

Mobile SDK reference

Full API reference for the OneSignal Mobile SDKs.

​
FAQ

​
What happens if I change my OneSignal App ID in my app?

Changing the OneSignal App ID in your app’s initialization code will create a brand new user and push subscription under the new App ID when the user updates and opens the app to the latest version. If your iOS bundle ID and/or Android package ID are the same, then the device will continue with the same push subscription status. The user data will be brand new i.e. you will need to add back your aliases, tags, email address, phone number on the new record. If the iOS bundle ID or Android package ID are different, then this is a brand new app and should have different push certs/keys.

​
Can OneSignal send push notifications in an on-premise closed network?

This can work as long as the computers on your closed network have access to the push gateway servers that you want to support: If the network is completely disconnected from the Internet, push notifications cannot be delivered via the standard OS/browser services, which is what we support.