docs(java): Document OpenTelemetry BOM alignment

docs/platforms/java/common/opentelemetry/setup/agentless.mdx

@@ -11,6 +11,76 @@ If you do not want to use our recommended <PlatformLink to="/opentelemetry/setup
 
 <PlatformContent includePath="performance/opentelemetry-install/without-java-agent" />
 
+## OpenTelemetry Dependency Alignment
+
+Sentry's Java OpenTelemetry integrations are tested with a specific OpenTelemetry dependency set. If your application also imports a BOM that manages OpenTelemetry versions, such as Spring Boot dependency management, it can override transitive OpenTelemetry dependencies and create a mixed OpenTelemetry classpath.
+
+Import `io.sentry:sentry-opentelemetry-bom` manually when another BOM manages OpenTelemetry versions in your application.
+
+<PlatformSection notSupported={["java.spring", "java.spring-boot"]}>
+
+```groovy {tabTitle:Gradle}{filename:build.gradle}
+dependencies {
+    implementation platform('io.sentry:sentry-opentelemetry-bom:{{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}')
+}
+```
+
+```xml {tabTitle:Maven}{filename:pom.xml}
+<dependencyManagement>
+    <dependencies>
+        <!-- If another Maven BOM also manages OpenTelemetry versions, import Sentry's OpenTelemetry BOM before that BOM. -->
+        <dependency>
+            <groupId>io.sentry</groupId>
+            <artifactId>sentry-opentelemetry-bom</artifactId>
+            <version>{{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+</PlatformSection>
+
+<PlatformSection supported={["java.spring", "java.spring-boot"]}>
+
+When using Gradle with Spring dependency management, import Sentry's OpenTelemetry BOM:
+
+```groovy {tabTitle:Gradle}{filename:build.gradle}
+dependencyManagement {
+    imports {
+        mavenBom 'io.sentry:sentry-opentelemetry-bom:{{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}'
+    }
+}
+```
+
+When using Maven, import Sentry's OpenTelemetry BOM before `spring-boot-dependencies`:
+
+```xml {tabTitle:Maven}{filename:pom.xml}
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>io.sentry</groupId>
+            <artifactId>sentry-opentelemetry-bom</artifactId>
+            <version>{{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-dependencies</artifactId>
+            <version>${spring-boot.version}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+If you use `spring-boot-starter-parent`, import Sentry's OpenTelemetry BOM in the child POM's `dependencyManagement` section.
+
+</PlatformSection>
+
 ## Usage
 
 You'll have to configure both OpenTelemetry and Sentry to see transactions in Sentry and have errors linked to transactions created by OpenTelemetry.

docs/platforms/java/common/opentelemetry/setup/otlp.mdx

@@ -47,6 +47,76 @@ This includes `sentry-opentelemetry-otlp` and the OpenTelemetry Spring Boot star
 
 </PlatformSection>
 
+## OpenTelemetry Dependency Alignment
+
+Sentry's Java OpenTelemetry integrations are tested with a specific OpenTelemetry dependency set. If your application also imports a BOM that manages OpenTelemetry versions, such as Spring Boot dependency management, it can override transitive OpenTelemetry dependencies and create a mixed OpenTelemetry classpath.
+
+Import `io.sentry:sentry-opentelemetry-bom` manually when another BOM manages OpenTelemetry versions in your application.
+
+<PlatformSection notSupported={["java.spring", "java.spring-boot"]}>
+
+```groovy {tabTitle:Gradle}{filename:build.gradle}
+dependencies {
+    implementation platform('io.sentry:sentry-opentelemetry-bom:{{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}')
+}
+```
+
+```xml {tabTitle:Maven}{filename:pom.xml}
+<dependencyManagement>
+    <dependencies>
+        <!-- If another Maven BOM also manages OpenTelemetry versions, import Sentry's OpenTelemetry BOM before that BOM. -->
+        <dependency>
+            <groupId>io.sentry</groupId>
+            <artifactId>sentry-opentelemetry-bom</artifactId>
+            <version>{{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+</PlatformSection>
+
+<PlatformSection supported={["java.spring", "java.spring-boot"]}>
+
+When using Gradle with Spring dependency management, import Sentry's OpenTelemetry BOM:
+
+```groovy {tabTitle:Gradle}{filename:build.gradle}
+dependencyManagement {
+    imports {
+        mavenBom 'io.sentry:sentry-opentelemetry-bom:{{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}'
+    }
+}
+```
+
+When using Maven, import Sentry's OpenTelemetry BOM before `spring-boot-dependencies`:
+
+```xml {tabTitle:Maven}{filename:pom.xml}
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>io.sentry</groupId>
+            <artifactId>sentry-opentelemetry-bom</artifactId>
+            <version>{{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-dependencies</artifactId>
+            <version>${spring-boot.version}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+If you use `spring-boot-starter-parent`, import Sentry's OpenTelemetry BOM in the child POM's `dependencyManagement` section.
+
+</PlatformSection>
+
 ## Setup
 
 You need to configure both OpenTelemetry (to export spans via OTLP to Sentry) and Sentry (to read trace/span IDs from OpenTelemetry).
@@ -130,4 +200,4 @@ The Sentry propagator inherits the sampling decision from the incoming `sentry-t
 
 If you need to control sampling for deferred traces, you have to implement a custom OpenTelemetry `Sampler`.
 
-</Alert>
+</Alert>

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

@@ -0,0 +1,25 @@
+---
+title: Troubleshooting
+sdk: sentry.java.opentelemetry-agentless
+description: "Troubleshoot Java OpenTelemetry problems."
+sidebar_order: 400
+---
+
+## OpenTelemetry Dependency Version Mismatches
+
+OpenTelemetry integrations use several artifacts that must stay on compatible versions. If another BOM or dependency-management plugin changes some OpenTelemetry versions but not others, your application can start with a mixed OpenTelemetry classpath.
+
+This is common in Spring Boot applications because Spring Boot dependency management can manage OpenTelemetry core artifacts while your application, Sentry, or another library brings in OpenTelemetry instrumentation artifacts. Version mismatches often appear as startup or request-time classloading errors, such as `ClassNotFoundException`, `NoClassDefFoundError`, `NoSuchMethodError`, or `NoSuchFieldError`.
+
+### Fix Dependency Alignment
+
+If you use Sentry's OpenTelemetry agentless or OTLP integrations and another BOM manages OpenTelemetry versions, manually import Sentry's OpenTelemetry BOM. The BOM aligns Sentry's OpenTelemetry modules with the OpenTelemetry core, instrumentation, and incubator artifacts Sentry tests against.
+
+Use the dependency alignment instructions for your integration:
+
+- <PlatformLink to="/opentelemetry/setup/agentless/#opentelemetry-dependency-alignment">
+    Agentless dependency alignment
+  </PlatformLink>
+- <PlatformLink to="/opentelemetry/setup/otlp/#opentelemetry-dependency-alignment">
+    OTLP dependency alignment
+  </PlatformLink>