# Troubleshooting | Sentry for React Native

## [Support 16 KB Page Sizes on Android](https://docs.sentry.io/platforms/react-native/troubleshooting.md#support-16-kb-page-sizes-on-android)

Starting with Android 15, AOSP supports devices with a 16 KB page size. If your app uses NDK libraries (directly or via an SDK), you'll need to rebuild it for compatibility with these devices.

Update to Sentry React Native SDK version `6.3.0` and above order to support 16 KB page sizes on Android devices.

Please read the [Android developer documentation](https://developer.android.com/guide/practices/page-sizes) to update and test your app with 16 KB page size support.

## ["Missing API declaration" after App Store review](https://docs.sentry.io/platforms/react-native/troubleshooting.md#missing-api-declaration-after-app-store-review)

Starting May 1, 2024, Apple requires all apps submitted to the App Store to provide a list of privacy-related APIs they use, including the reasons under which they use it. If you received an email from Apple with the message "ITMS-91053: Missing API declaration", your app doesn't fulfill the requirements. To solve this, follow our [Apple Privacy Manifest](https://docs.sentry.io/platforms/react-native/data-management/apple-privacy-manifest.md) guide.

## [App Start Numbers Are Too High To Be Accurate](https://docs.sentry.io/platforms/react-native/troubleshooting.md#app-start-numbers-are-too-high-to-be-accurate)

iOS 15 introduced a feature called pre-warm that affected the calculations the Sentry SDK does. This issue was fixed in version [4.1.1](https://github.com/getsentry/sentry-react-native/releases/tag/4.1.1) of the SDK. Please update to this version or a later one.

For more details, [see the troubleshooting page for the iOS SDK](https://docs.sentry.io/platforms/apple/troubleshooting.md#wrong-app-start-data).

## [Unhandled Promise Rejections](https://docs.sentry.io/platforms/react-native/troubleshooting.md#unhandled-promise-rejections)

Due to an issue with React Native's dependencies, unhandled promise rejections might not be correctly caught by Sentry. If the promise rejection handler was not correctly attached, our SDK might issue a warning:

> WARN: Unhandled promise rejections might not be caught by Sentry. Read about how to fix this on our troubleshooting docs.

Otherwise, we will let you know that the handler is attached:

> \[Sentry] Unhandled promise rejections will be caught by Sentry.

You can read more about how to set up unhandled promise rejections in the [Unhandled Promise Rejections guide](https://docs.sentry.io/platforms/react-native/integrations/unhandled-rejections.md).

## [Source Maps](https://docs.sentry.io/platforms/react-native/troubleshooting.md#source-maps)

When there is an issue with source maps on your event, there will usually be an error dialog at the top of the Issue Details page in [sentry.io](https://sentry.io):

> There was 1 problem processing this event: Source code was not found

Common fixes to this issue include:

* Checking that both the `release` and `dist` and are set on the event by [setting it in the call to `init`](https://docs.sentry.io/platforms/react-native/configuration/releases.md#bind-the-version).
* Checking that source maps are correctly uploaded with the exact same `release` and `dist` values as the event. They **must match** for source maps to upload correctly.
* If you set a custom `release` and `dist`, confirming that you manually uploaded the sourcemaps since our automatic source map upload script will not detect the custom values.
* Make sure that the name of the bundle in the stack trace matches exactly with the name in the source map. For example, if your stack frames say `app:///index.bundle`, the artifacts must be named `index.bundle` and `index.bundle.map` respectively.
* Checking that you're not disabling the [`RewriteFrames`](https://docs.sentry.io/platforms/javascript/configuration/integrations/rewriteframes.md) default integration by overwriting it, filtering it out, or setting `defaultIntegrations: false`.

[For more details, please read the guide on React Native source maps.](https://docs.sentry.io/platforms/react-native/sourcemaps.md)

### [Source Maps With Hermes](https://docs.sentry.io/platforms/react-native/troubleshooting.md#source-maps-with-hermes)

Although the build script should already handle this for you most of the time, you may need to perform some extra steps when using the source maps with the Hermes engine. [You can follow the guide here.](https://docs.sentry.io/platforms/react-native/manual-setup/hermes.md#custom-source-maps).

### [Different Bundles for Different Platforms](https://docs.sentry.io/platforms/react-native/troubleshooting.md#different-bundles-for-different-platforms)

Your app could have different bundles for each platform that it supports, such as iOS and Android. To associate the correct bundle and sourcemap to each platform, you will need a unique release/dist combination for each platform. An easy way to do this is to include the platform name in the `dist` value.

## [iOS Build Script Failed](https://docs.sentry.io/platforms/react-native/troubleshooting.md#ios-build-script-failed)

If you're using an older version of the SDK (version `3.2.12` or lower) or `sentry-cli` (version `1.71.0` or lower), try passing `--force-foreground` to the Sentry CLI command in the build script:

```bash
# ...
../node_modules/@sentry/cli/bin/sentry-cli react-native xcode \
  ../node_modules/react-native/scripts/react-native-xcode.sh --force-foreground
```

## [Release Health](https://docs.sentry.io/platforms/react-native/troubleshooting.md#release-health)

If your release health statistics are being attributed to the wrong release, confirm that you [pass the `release` and `dist` to the `init` call](https://docs.sentry.io/platforms/react-native/configuration/releases.md#bind-the-version).

If you are using Code Push, check that you are not using `setRelease` and `setDist` as they will break release health. You can read more on the [CodePush guide](https://docs.sentry.io/platforms/react-native/manual-setup/codepush.md).

## [Minified Names in Production](https://docs.sentry.io/platforms/react-native/troubleshooting.md#minified-names-in-production)

When bundling for production, React Native will minify class and function names to reduce the bundle size. This means that you won't get the full original component names in your Touch Event breadcrumbs or Profiler spans.

A way to work around this is to set the `displayName` on all the components you want to track with touch events or to pass the `name` prop to the Profiler components. However, you can also configure Metro bundler to not minify function names by setting these options in `metro.config.js`:

`metro.config.js`

```javascript
module.exports = {
  transformer: {
    minifierConfig: {
      keep_classnames: true, // Preserve class names
      keep_fnames: true, // Preserve function names
      mangle: {
        keep_classnames: true, // Preserve class names
        keep_fnames: true, // Preserve function names
      },
    },
  },
};
```

This setting applies to **all** class and function names — not just React components — and could increase your JS bundle size.

## [Missing Context on Android NDK Events](https://docs.sentry.io/platforms/react-native/troubleshooting.md#missing-context-on-android-ndk-events)

If the context - such as breadcrumbs, user, etc. - is missing on Android NDK events, you need to enable the [Scope Synchronization](https://docs.sentry.io/platforms/react-native/enriching-events/scopes.md#scope-synchronization) feature.

## [Using node with nvm or Volta](https://docs.sentry.io/platforms/react-native/troubleshooting.md#using-node-with-nvm-or-volta)

Xcode has trouble locating the default node binary if you're using nvm or Volta. To troubleshoot this, add `node` binary path to the *Bundle React Native code and images* build phase like this:

```bash
export NODE_BINARY=path/to/your/node
# ... rest of the script
```

Or execute this `ln -s $(which node) /usr/local/bin/node` in your terminal.

## [NavigationContainer reset the ref each render](https://docs.sentry.io/platforms/react-native/troubleshooting.md#navigationcontainer-reset-the-ref-each-render)

If you're using `React Navigation 5` and you're not receiving transactions anymore, it might be because of [this bug](https://github.com/react-navigation/react-navigation/issues/9213). Upgrading to `React Navigation 6` should solve the issue, but if not, file an issue in our [repo](https://github.com/getsentry/sentry-react-native).

## [RAM Bundles Mismatched Line Numbers](https://docs.sentry.io/platforms/react-native/troubleshooting.md#ram-bundles-mismatched-line-numbers)

If you experience mismatched line numbers on [sentry.io](https://sentry.io) when using RAM Bundles, this is due to a [bug](https://github.com/facebook/metro/issues/399) on the Metro tooling.

## [Uploading source maps from Xcode Cloud](https://docs.sentry.io/platforms/react-native/troubleshooting.md#uploading-source-maps-from-xcode-cloud)

The Xcode integration reads `dist` from `CFBundleVersion` but Xcode Cloud builds use `CI_BUILD_NUMBER` variable. Add the following code to `Bundle React Native code and images` build phase to enable correct source maps uploads.

```bash
export SENTRY_DIST=$CI_BUILD_NUMBER
```

## [iOS: Sentry User Feedback UI cannot be used from app extensions.](https://docs.sentry.io/platforms/react-native/troubleshooting.md#ios-sentry-user-feedback-ui-cannot-be-used-from-app-extensions)

If you see an error similar to `'SentryUserFeedbackIntegration' is unavailable: not available on iOS - Sentry User Feedback UI cannot be used from app extensions` during the application build process, please make sure that the `APPLICATION_EXTENSION_API_ONLY` is set to `NO`. You can achieve that with the following in your `Podfile`.

`ios/Podfile`

```ruby
installer.pods_project.targets.each do |target|
  target.build_configurations.each do |config|
    if target.name == 'Sentry'
      config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'NO'
    end
  end
end
```

## [Unknown receiver '\<SomeReceiver>', Use of undeclared identifier '\<SomeIdentifier>'](https://docs.sentry.io/platforms/react-native/troubleshooting.md#unknown-receiver-somereceiver-use-of-undeclared-identifier-someidentifier)

If you see an error like `Unknown receiver 'SwiftDescriptor'` or `Use of undeclared identifier 'SentryLog'` during the application build process (in SDK versions prior to `6.18.0`), there's a conflict stemming from `APPLICATION_EXTENSION_API_ONLY`. By default, the Sentry Cocoapod is configured with `APPLICATION_EXTENSION_API_ONLY=YES`, but some `post_install` script likely changed it. To fix this error, add the following to the `Podfile`.

`ios/Podfile`

```ruby
post_install do |installer|
  react_native_post_install(
    installer,
    config[:reactNativePath],
    :mac_catalyst_enabled => false,
  )

  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      if target.name == 'Sentry'
        config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'YES'
      else
        # configuration for other targets
      end
    end
  end
end
```

## [Using Gradle `configureondemand`](https://docs.sentry.io/platforms/react-native/troubleshooting.md#using-gradle-configureondemand)

If you have enabled Gradle's `org.gradle.configureondemand` feature, you'll need a clean build, or you'll need to disable this feature to upload the source map on every build.

To disable this feature, set `org.gradle.configureondemand=false` or remove it as its default value is disabled, do this in the `gradle.properties` file.

## [Set Up SDK v4 With React Native 0.69 or Higher](https://docs.sentry.io/platforms/react-native/troubleshooting.md#set-up-sdk-v4-with-react-native-069-or-higher)

To install an older version of the `@sentry/react-native`, you'll need to specify it in the install command. Similarly, you'll need to use a compatible `@sentry/wizard`, as shown in the script below.

```bash
yarn add @sentry/react-native@4
npx @sentry/wizard@1 -i reactNative -p ios android
npx pod-install
```

Before building the app, check that the `android/app/build.gradle` was patched with the following Gradle integration:

```groovy
apply from: "../../node_modules/@sentry/react-native/sentry.gradle"
```

While this should work on Android, it will still fail in the `Bundle React Native code and images` build step phase on iOS. To fix this, revert the patched `shellScript` in the `ios/$projectName.xcodeproj/project.pbxproj` file, (where `$projectName` is likely your project's name). Then search for the build step phase `Bundle React Native code and images` and patch the `shellScript`.

*Old*:

```bash
shellScript = "set -e\n\nWITH_ENVIRONMENT=\"../node_modules/react-native/scripts/xcode/with-environment.sh\"\nREACT_NATIVE_XCODE=\"../node_modules/react-native/scripts/react-native-xcode.sh\"\n\n/bin/sh -c \"$WITH_ENVIRONMENT $REACT_NATIVE_XCODE\"\n";
```

*New*:

```bash
shellScript = "set -e\nexport SENTRY_PROPERTIES=sentry.properties\nexport EXTRA_PACKAGER_ARGS=\"--sourcemap-output $DERIVED_FILE_DIR/main.jsbundle.map\"\nWITH_ENVIRONMENT=\"../node_modules/react-native/scripts/xcode/with-environment.sh\"\nREACT_NATIVE_XCODE=\"../node_modules/react-native/scripts/react-native-xcode.sh\"\nSENTRY_CLI_PATH=\"../node_modules/@sentry/cli/bin/sentry-cli\"\n/bin/sh -c \"$WITH_ENVIRONMENT \\\"$SENTRY_CLI_PATH react-native xcode $REACT_NATIVE_XCODE\\\"\"";
```

If your build is failing because of outdated fields in the `react-native.config.js`, update the config file, located in `node_modules/@sentry/react-native/react-native.config.js`. This is required for React Native, v0.69. For now, newer versions only show a warning.

*Old*:

```javascript
module.exports = {
  dependency: {
    platforms: {
      ios: {
        sharedLibraries: ["libz"],
      },
      android: {
        packageInstance: "new RNSentryPackage()",
      },
    },
    hooks: {
      postlink:
        "node node_modules/@sentry/wizard/dist/bin.js -i reactNative -p ios android",
      postunlink:
        "node node_modules/@sentry/wizard/dist/bin.js -i reactNative -p ios android --uninstall",
    },
  },
};
```

*New*:

```javascript
module.exports = {
  dependency: {
    platforms: {
      ios: {},
      android: {
        packageInstance: "new RNSentryPackage()",
      },
    },
  },
};
```

## [React Native 0.60.3 Failing Build](https://docs.sentry.io/platforms/react-native/troubleshooting.md#react-native-0603-failing-build)

React Native 0.60.3 tooling was unexpectedly moving source maps files, which caused the Sentry Gradle plugin to fail. This was fixed in version 0.60.4. For more detailed information, follow the [issue](https://github.com/getsentry/sentry-react-native/issues/2442).

## [SDK v5.10.0 and Older Xcode Build Phases](https://docs.sentry.io/platforms/react-native/troubleshooting.md#sdk-v5100-and-older-xcode-build-phases)

If you're using SDK v5.10.0 or older, use the following build phases in Xcode. If you are using SDK v5.11.0 or newer, read the current [Manual Setup](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md).

`Bundle React Native code and images`

```bash
export SENTRY_PROPERTIES=sentry.properties
export EXTRA_PACKAGER_ARGS="--sourcemap-output $DERIVED_FILE_DIR/main.jsbundle.map"
set -e

# RN 0.69+
WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
REACT_NATIVE_XCODE="../node_modules/react-native/scripts/react-native-xcode.sh"
SENTRY_CLI="../node_modules/@sentry/cli/bin/sentry-cli"

/bin/sh -c "$WITH_ENVIRONMENT \"$SENTRY_CLI react-native xcode $REACT_NATIVE_XCODE\""

# RN 0.46 – 0.68
# ../node_modules/@sentry/cli/bin/sentry-cli react-native xcode \
#  ../node_modules/react-native/scripts/react-native-xcode.sh

# All versions
/bin/sh ../node_modules/@sentry/react-native/scripts/collect-modules.sh
```

And Build Phase for native debug symbols upload.

`Upload Debug Symbols to Sentry`

```bash
export SENTRY_PROPERTIES=sentry.properties

[[ $SENTRY_INCLUDE_NATIVE_SOURCES == "true" ]] && INCLUDE_SOURCES_FLAG="--include-sources" || INCLUDE_SOURCES_FLAG=""
SENTRY_CLI="../node_modules/@sentry/cli/bin/sentry-cli"
$SENTRY_CLI debug-files upload "$INCLUDE_SOURCES_FLAG" "$DWARF_DSYM_FOLDER_PATH"
```

## [Missing Java stack trace on the New Architecture](https://docs.sentry.io/platforms/react-native/troubleshooting.md#missing-java-stack-trace-on-the-new-architecture)

If you're using the new architecture on React Native, you might be missing the Java stack trace. Follow the [issue](https://github.com/facebook/react-native/issues/34923) for more information.

## [Failing Build Due to `sentry-cli`](https://docs.sentry.io/platforms/react-native/troubleshooting.md#failing-build-due-to-sentry-cli)

If your build fails due to Sentry CLI error, because you don't have internet connection, or because [sentry.io](https://sentry.io) is down, you can allow failure of the `sentry-cli` step by adding an environmental variable `SENTRY_ALLOW_FAILURE` equal to `true`. The CLI will still run, but won't cause the build to fail:

```bash
# iOS
SENTRY_ALLOW_FAILURE=true npx react-native run-ios

# Android
SENTRY_ALLOW_FAILURE=true npx react-native run-android
```

Note that if the source maps upload fails, you'll have to do it [manually](https://docs.sentry.io/platforms/react-native/sourcemaps.md) later when the connection is restored.

When you remove the environmental variable in front of your build command, your build will work as before.

## [Expo Transactions Never Finish](https://docs.sentry.io/platforms/react-native/troubleshooting.md#expo-transactions-never-finish)

If you're using [expo-dev-client](https://docs.expo.dev/development/introduction/#what-is-an-expo-dev-client), you might notice that transactions never finish in your dev builds. This is due to logs that the dev client is continuously sending to the development server. To fix this, you can stop creating spans for the HTTP requests to the log endpoint in your dev builds by adding the following to your `Sentry.init()`:

```javascript
import * as Sentry from "sentry-expo";
import * as Network from "expo-network";

const devServerPort = 8081;
let devServerIpAddress: string | null = null;
Network.getIpAddressAsync().then((ip) => {
  devServerIpAddress = ip;
});

Sentry.init({
  tracesSampleRate: 1.0,
  integrations: [
    new Sentry.Native.ReactNativeTracing({
      shouldCreateSpanForRequest: (url) => {
        return (
          !__DEV__ ||
          !url.startsWith(`http://${devServerIpAddress}:${devServerPort}/logs`)
        );
      },
    }),
  ],
});
```

## [Routing Transaction Data Contains Sensitive Information](https://docs.sentry.io/platforms/react-native/troubleshooting.md#routing-transaction-data-contains-sensitive-information)

If you use automatic routing instrumentation for React Navigation, sensitive data you put in routing parameters can get sent to Sentry. You can prevent this by either updating the SDK to [5.15.2](https://github.com/getsentry/sentry-react-native/releases/tag/5.15.2) or higher, or dropping the data manually with `beforeSendTransaction`:

```javascript
Sentry.init({
  dsn: "...",
  beforeSendTransaction: (event) => {
    // delete params as they may contain PII
    delete event.contexts?.trace?.data?.route?.params;
    delete event.contexts?.trace?.data?.previousRoute?.params;

    return event;
  },
});
```

You can also use [Advanced Data Scrubbing](https://docs.sentry.io/security-legal-pii/scrubbing/advanced-datascrubbing.md) to filter out sensitive data before it is stored on the server side:

```bash
[Replace] [Anything] from [contexts.trace.data.route.params]
[Replace] [Anything] from [contexts.trace.data.previousRoute.params]
```

## [Sentry Android Gradle Plugin Circular Dependency](https://docs.sentry.io/platforms/react-native/troubleshooting.md#sentry-android-gradle-plugin-circular-dependency)

If you encounter a circular dependency error when building your Android app with the Sentry Android Gradle Plugin, this is typically caused by using an older version of the Android Gradle Plugin (AGP).

### [Error Example](https://docs.sentry.io/platforms/react-native/troubleshooting.md#error-example)

You might see an error similar to:

```bash
Circular dependency between the following tasks:
:app:compileReleaseJavaWithJavac
:app:generateSentryProguardUuidProductionRelease
```

### [Solution](https://docs.sentry.io/platforms/react-native/troubleshooting.md#solution)

Update your Android Gradle Plugin to version **7.4** or higher. In your `android/build.gradle` (project-level) file:

`android/build.gradle`

```groovy
buildscript {
    dependencies {
        classpath("com.android.tools.build:gradle:7.4.0") // or higher
    }
}
```

Or if using the plugins block in your `android/app/build.gradle`:

`android/app/build.gradle`

```groovy
plugins {
    id "com.android.application" version "7.4.0" // or higher
}
```

AGP 7.4+ introduced new APIs for injecting into assets that the Sentry Android Gradle Plugin uses to avoid this circular dependency. Since AGP 7.4 was released in 2023, we recommend upgrading to the latest stable version.

For more information, see [GitHub issue #756](https://github.com/getsentry/sentry-android-gradle-plugin/issues/756).