Version

Troubleshooting

Updated August 17, 2026

If you're having trouble with the SDK, here are some basic steps to troubleshoot your problems, and solutions to some known issues.

Basic troubleshooting steps

Make sure your app meets our prerequisites: Attempting to use our SDK in an environment that doesn't match our supported versions may result in build errors.

Troubleshooting issues with our MCP server

Our MCP server includes an integration tool that can help troubleshoot your implementation, including problems with push and in-app notifications. It has a deep understanding of our SDKs and provides an immediate way to get support with your implementation—without necessarily needing to capture debug logs, etc.

You can ask the MCP server basic questions like, “My push notifications aren’t working. Can you help me troubleshoot the problem?”

Or you can ask more specific questions like, “Deep links in push notifications don’t work for customers in my Android app.” Or “I’m not receiving metrics for push notifications for iOS users.”

The tool will return detailed steps to help you find and troubleshoot problems.

Capture logs

Logs help us pinpoint the problem and find a solution.

Enable debug logging in your app.

import { CustomerIO, CioConfig, CioLogLevel } from 'customerio-reactnative';

const config: CioConfig = {
   CioApiKey: 'Your CDP API Key',
   logLevel: CioLogLevel.Debug,
}

CustomerIO.initialize(config) ;

Build and run your app on a physical device or emulator.

In the console, run:

react-native log-ios
react-native log-android

Export your log to a text file and send it to our Support team at win@customer.io. In your message, describe your problem and provide relevant information about:
- The version of the SDK you’re using.
- The type of problem you’ve encountered.
- An existing GitHub issue URL or existing support email so we know what these log files are in reference to.

NaN, infinite, or imaginary number values

Customer.io doesn’t handle invalid JSON values in your payloads, like NaN, infinite, or imaginary number values. If you send these values in identify, track, screen, or similar calls, we’ll drop them and record errors.

While we drop invalid values, we don’t drop the entire payload. The operation itself will still succeed. For example, if you send an identify call with two attributes, one of which is a NaN value, we’ll drop the NaN value, but the identify call succeeds with the other attribute.

Push notification issues

{{% include “integrations/sdk/push-troubleshoot-nse-target.md” %}}

Image display issues

Try updating iOS package dependencies

This SDK uses our iOS push package. In some cases, we may make fixes in our iOS packages that fix downstream issues in, or expose new features to this SDK. You can update the version in your podfile and then run the following command to get the latest iOS packages.

Our instructions above list out the full version of the iOS push package. If you want to automatically increment packages, you can remove the patch and minor build numbers (the second and third parts of the version number), and pod update will automatically fetch the latest package versions. However, please understand that fetching the latest versions can cause build issues if the latest iOS package doesn’t agree with code in your app!

pod update --repo-update --project-directory=ios

Error: Push notifications not working

If push notifications don’t work, make sure that you’ve initialized the Customer.io SDK in your AppDelegate.swift file. You must initialize the SDK in the application(_:didFinishLaunchingWithOptions:) method.

@main
class AppDelegateWithCioIntegration: CioAppDelegateWrapper<AppDelegate> {}

class AppDelegate: NSObject, UIApplicationDelegate {
  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    ...
    
    // Initialize the Customer.io SDK for push notifications
    MessagingPushAPN.initialize(withConfig: MessagingPushConfigBuilder().build())

    return true
  }
}

Deep linking to iOS when your app is killed

There’s a known issue preventing deep links from working when your app is closed on iOS devices. When the app is in a closed state, the native click event fires before the app’s lifecycle begins. We recommend a workaround:

Update didFinishLaunchingWithOptions in your AppDelegate.swift file with the code below. We extract the deep link from the push notification payload and add it to the launch options, ensuring that your React Native app receives the link when it starts.

func application(_ application: UIApplication, 
                didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let delegate = ReactNativeDelegate()
    let factory = RCTReactNativeFactory(delegate: delegate)

    ...

    if var launchOptions = launchOptions,
       let remotePush = launchOptions[UIApplication.LaunchOptionsKey.remoteNotification] as? [String: [String: [String: String]]],
       let link = remotePush["CIO"]?["push"]?["link"], let url = URL(string:link),
       launchOptions[UIApplication.LaunchOptionsKey.url] == nil
    {
       launchOptions[UIApplication.LaunchOptionsKey.url] = url
    }

    let appName = Bundle.main.displayName
    factory.startReactNative(
        withModuleName: appName,
        in: window,
        initialProperties: ["appName": appName],
        launchOptions: launchOptions
    )

    ...
}

Compiler error: ‘X’ is unavailable in application extensions for iOS

This error occasionally occurs when users add a notification extension to handle rich push messages. If you see this error, try the following steps:

Add this code to the end of your Podfile:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    if target.name.start_with?('CustomerIO')
      puts "Modifying target #{target.name} with workaround"
      
      target.build_configurations.each do |config|
        puts "Setting build config settings for #{target.name}"
        config.build_settings['APPLICATION_EXTENSION_API_ONLY'] ||= 'NO'
      end
    end
  end
end

In the root directory of your app, run pod install --project-directory=ios. This command will apply the above workaround to your project.
Try to compile your app again.

If you still see the error message, it’s likely that the error you see is related to a different SDK that you use in your app and not the Customer.io SDK. We suggest that you contact the developers of the SDK that you see in the error message for help.

If you don’t see an error message, send our technical support team a message with:

The error message that you see when compiling your app.
The contents of your ios/Podfile and ios/Podfile.lock files.
The version of the React Native SDK that you are using.

Deep links on iOS only open in a browser

It sounds like you want to use universal links, links that go to your app if a person has your app installed and to your website if they don't. Universal links are a bit different than your average deep link and require a little bit of additional setup.