From bae1d714931b846d387ef6240f629d1ceb5fef51 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Wed, 15 Apr 2026 17:02:16 +0200 Subject: [PATCH 1/2] docs(react-native): Add warning about AGP autoInstallation on Android Add alerts to manual setup and v7-to-v8 migration guides warning that the Sentry Android Gradle Plugin autoInstallation must be disabled for React Native. Add a troubleshooting section for the IllegalStateException mix of versions crash caused by this misconfiguration. Refs https://github.com/getsentry/sentry-react-native/issues/5682 Co-Authored-By: Claude --- .../manual-setup/manual-setup.mdx | 7 +++++ .../react-native/migration/v7-to-v8.mdx | 6 +++++ .../react-native/troubleshooting/index.mdx | 26 +++++++++++++++++++ 3 files changed, 39 insertions(+) diff --git a/docs/platforms/react-native/manual-setup/manual-setup.mdx b/docs/platforms/react-native/manual-setup/manual-setup.mdx index bf994951660fc..eadafa9900d64 100644 --- a/docs/platforms/react-native/manual-setup/manual-setup.mdx +++ b/docs/platforms/react-native/manual-setup/manual-setup.mdx @@ -185,6 +185,12 @@ buildscript { You can configure the plugin options in `android/app/build.gradle`, as shown below: + + +The `autoInstallation` option **must** be set to `false` when using the Sentry Android Gradle Plugin with React Native. The `@sentry/react-native` SDK manages its own `sentry-android` dependency. If auto-installation is enabled, the plugin may pull in a different `sentry-android` version, causing an `IllegalStateException: Sentry SDK has detected a mix of versions` crash at app startup. + + + ```groovy {filename:android/app/build.gradle} apply plugin: "io.sentry.android.gradle" @@ -207,6 +213,7 @@ sentry { // which might be incompatible with the React Native SDK // Enable auto-installation of Sentry components (sentry-android SDK and okhttp, timber and fragment integrations). // Default is enabled. + // IMPORTANT: Must be false for React Native. autoInstallation { enabled = false } diff --git a/docs/platforms/react-native/migration/v7-to-v8.mdx b/docs/platforms/react-native/migration/v7-to-v8.mdx index 9edcc73e62e18..48220a2ae2aeb 100644 --- a/docs/platforms/react-native/migration/v7-to-v8.mdx +++ b/docs/platforms/react-native/migration/v7-to-v8.mdx @@ -61,6 +61,12 @@ buildscript { } ``` + + +If you use the Sentry Android Gradle Plugin (AGP), make sure `autoInstallation` is **disabled** in your `android/app/build.gradle`. The `@sentry/react-native` SDK ships with its own compatible `sentry-android` dependency. If `autoInstallation` is enabled, the plugin may pull in a different `sentry-android` version, causing an `IllegalStateException: Sentry SDK has detected a mix of versions` crash at app startup. See the [manual setup guide](/platforms/react-native/manual-setup/manual-setup/#enable-sentry-agp) for the correct configuration. + + + #### Sentry Self-Hosted Sentry CLI v3 requires self-hosted Sentry instances version **25.11.1+** (previously 25.2.0). diff --git a/docs/platforms/react-native/troubleshooting/index.mdx b/docs/platforms/react-native/troubleshooting/index.mdx index da86a37221898..95306e9b791dd 100644 --- a/docs/platforms/react-native/troubleshooting/index.mdx +++ b/docs/platforms/react-native/troubleshooting/index.mdx @@ -359,6 +359,32 @@ You can also use [Advanced Data Scrubbing](/security-legal-pii/scrubbing/advance [Replace] [Anything] from [contexts.trace.data.previousRoute.params] ``` +## Android: IllegalStateException Mix of Versions + +If your Android app crashes on startup with: + +``` +IllegalStateException: Sentry SDK has detected a mix of versions +``` + +This is caused by the Sentry Android Gradle Plugin (AGP) auto-installing a `sentry-android` version that conflicts with the one shipped by `@sentry/react-native`. + +### Solution + +Set `autoInstallation.enabled = false` in your `android/app/build.gradle`: + +```groovy {filename:android/app/build.gradle} +sentry { + autoInstallation { + enabled = false + } +} +``` + +The React Native SDK manages its own compatible `sentry-android` dependency, so the Gradle plugin should not auto-install one. See the [manual setup guide](/platforms/react-native/manual-setup/manual-setup/#enable-sentry-agp) for the full configuration. + +For more information, see [GitHub issue #5682](https://github.com/getsentry/sentry-react-native/issues/5682). + ## 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). From cdcc88a5489c0b09764de3eedaf656b7b797adbc Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Wed, 15 Apr 2026 17:07:13 +0200 Subject: [PATCH 2/2] fix(react-native): Update broken expo-dev-client docs link Expo restructured their docs, moving the development builds introduction from /development/introduction/ to /develop/development-builds/introduction/. Co-Authored-By: Claude --- docs/platforms/react-native/troubleshooting/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/react-native/troubleshooting/index.mdx b/docs/platforms/react-native/troubleshooting/index.mdx index 95306e9b791dd..476fd7499866e 100644 --- a/docs/platforms/react-native/troubleshooting/index.mdx +++ b/docs/platforms/react-native/troubleshooting/index.mdx @@ -308,7 +308,7 @@ When you remove the environmental variable in front of your build command, your ## 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()`: +If you're using [expo-dev-client](https://docs.expo.dev/develop/development-builds/introduction/), 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";