Troubleshooting Guide for mixed versions in Java / Android SDK

docs/platforms/android/troubleshooting/index.mdx

@@ -318,3 +318,5 @@ This problem is only relevant to these specific versions: `sentry-android-core`
 </Alert>
 
 Check [this issue](https://github.com/getsentry/sentry-android-gradle-plugin/issues/329) for more details.
+
+<PageGrid />

docs/platforms/android/troubleshooting/mixed-versions/index.mdx

@@ -0,0 +1,48 @@
+---
+title: Mixed Versions
+description: "Troubleshoot and resolve mixed Android SDK dependency versions."
+sidebar_order: 1000
+---
+
+Using multiple Android SDK dependencies with mixed versions is not supported as it is very likely this leads to a crash later on. For this reason we chose to crash the application on SDK init instead.
+
+## Multiple Dependencies With Mixed Versions
+
+The following snippet shows a mix of version caused by using `sentry` with version `8.6.0` and `sentry-android` with version `8.7.0`. To fix the issue please set the same version for all dependencies or use `sentry-bom`. This may also happen if you are using an internal library which has a different version defined.
+
+```groovy {tabTitle:Gradle}{filename:build.gradle}
+implementation('io.sentry:sentry:8.6.0')
+implementation('io.sentry:sentry-android:8.7.0')
+```
+```xml {tabTitle:Maven}{filename:pom.xml}
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>io.sentry</groupId>
+            <artifactId>sentry</artifactId>
+            <version>8.6.0</version>
+        </dependency>
+        <dependency>
+            <groupId>io.sentry</groupId>
+            <artifactId>sentry-android</artifactId>
+            <version>8.7.0</version>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+## Build Plugin And Explicit Dependency
+
+When using our Gradle or Maven plugin and manually defining additional Sentry Android SDK dependencies it is also possible to end up with mixed versions. The following snippet shows the plugin being configured to use version `8.0.0` but there is also an additional dependency that has been set to version `8.1.0`. To fix the issue please set the same version or use `sentry-bom`.
+
+```groovy {tabTitle:Gradle}{filename:build.gradle}
+dependencies {
+	implementation 'io.sentry:sentry-okhttp:8.1.0'
+}
+
+sentry {
+	autoInstallation {
+		sentryVersion = "8.0.0"
+	}
+}
+```

docs/platforms/java/common/troubleshooting/index.mdx

@@ -0,0 +1,7 @@
+---
+title: Troubleshooting
+description: "Troubleshoot and resolve common issues with the Java SDK."
+sidebar_order: 9000
+---
+
+<PageGrid />

docs/platforms/java/common/troubleshooting/mixed-versions/index.mdx

@@ -0,0 +1,52 @@
+---
+title: Mixed Versions
+description: "Troubleshoot and resolve mixed Java SDK dependency versions."
+sidebar_order: 1000
+---
+
+Using multiple Java SDK dependencies with mixed versions is not supported as it is very likely this leads to a crash later on. For this reason we chose to crash the application on SDK init instead.
+
+## Multiple Dependencies With Mixed Versions
+
+The following snippet shows a mix of version caused by using `sentry` with version `8.6.0` and `sentry-logback` with version `8.7.0`. To fix the issue please set the same version for all dependencies or <PlatformLink to="/configuration/bill-of-materials/">use `sentry-bom`</PlatformLink>. This may also happen if you are using an internal library which has a different version defined.
+
+```groovy {tabTitle:Gradle}{filename:build.gradle}
+implementation('io.sentry:sentry:8.6.0')
+implementation('io.sentry:sentry-logback:8.7.0')
+```
+```xml {tabTitle:Maven}{filename:pom.xml}
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>io.sentry</groupId>
+            <artifactId>sentry</artifactId>
+            <version>8.6.0</version>
+        </dependency>
+        <dependency>
+            <groupId>io.sentry</groupId>
+            <artifactId>sentry-logback</artifactId>
+            <version>8.7.0</version>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+## Build Plugin And Explicit Dependency
+
+When using our Gradle or Maven plugin and manually defining additional Sentry Java SDK dependencies it is also possible to end up with mixed versions. The following snippet shows the plugin being configured to use version `8.0.0` but there is also an additional dependency that has been set to version `8.1.0`. To fix the issue please set the same version or <PlatformLink to="/configuration/bill-of-materials/">use `sentry-bom`</PlatformLink>.
+
+```groovy {tabTitle:Gradle}{filename:build.gradle}
+dependencies {
+	implementation 'io.sentry:sentry-opentelemetry-agentless-spring:8.1.0'
+}
+
+sentry {
+	autoInstallation {
+		sentryVersion = "8.0.0"
+	}
+}
+```
+
+## Agent Version And Build Time Version
+
+When using `sentry-opentelemetry-agent` you may end up using a version of the Agent that differs from other Sentry Java SDK dependencies you are using as dependencies. This is also not supported. Please use the same version for `sentry-opentelemetry-agent` and all other Java SDK dependencies.