diff --git a/docs/platforms/java/common/opentelemetry/setup/agentless.mdx b/docs/platforms/java/common/opentelemetry/setup/agentless.mdx
index f2483a4e10307..ff2dfd58e90f2 100644
--- a/docs/platforms/java/common/opentelemetry/setup/agentless.mdx
+++ b/docs/platforms/java/common/opentelemetry/setup/agentless.mdx
@@ -11,6 +11,76 @@ If you do not want to use our recommended
+## 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.
+
+
+
+```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}
+
+
+
+
+ io.sentry
+ sentry-opentelemetry-bom
+ {{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}
+ pom
+ import
+
+
+
+```
+
+
+
+
+
+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}
+
+
+
+ io.sentry
+ sentry-opentelemetry-bom
+ {{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}
+ pom
+ import
+
+
+ org.springframework.boot
+ spring-boot-dependencies
+ ${spring-boot.version}
+ pom
+ import
+
+
+
+```
+
+If you use `spring-boot-starter-parent`, import Sentry's OpenTelemetry BOM in the child POM's `dependencyManagement` section.
+
+
+
## Usage
You'll have to configure both OpenTelemetry and Sentry to see transactions in Sentry and have errors linked to transactions created by OpenTelemetry.
diff --git a/docs/platforms/java/common/opentelemetry/setup/otlp.mdx b/docs/platforms/java/common/opentelemetry/setup/otlp.mdx
index 82452dcc4fb13..2d2d9fa2293aa 100644
--- a/docs/platforms/java/common/opentelemetry/setup/otlp.mdx
+++ b/docs/platforms/java/common/opentelemetry/setup/otlp.mdx
@@ -47,6 +47,76 @@ This includes `sentry-opentelemetry-otlp` and the OpenTelemetry Spring Boot star
+## 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.
+
+
+
+```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}
+
+
+
+
+ io.sentry
+ sentry-opentelemetry-bom
+ {{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}
+ pom
+ import
+
+
+
+```
+
+
+
+
+
+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}
+
+
+
+ io.sentry
+ sentry-opentelemetry-bom
+ {{@inject packages.version('sentry.java.opentelemetry-bom', '8.46.0') }}
+ pom
+ import
+
+
+ org.springframework.boot
+ spring-boot-dependencies
+ ${spring-boot.version}
+ pom
+ import
+
+
+
+```
+
+If you use `spring-boot-starter-parent`, import Sentry's OpenTelemetry BOM in the child POM's `dependencyManagement` section.
+
+
+
## 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`.
-
\ No newline at end of file
+
diff --git a/docs/platforms/java/common/opentelemetry/troubleshooting/index.mdx b/docs/platforms/java/common/opentelemetry/troubleshooting/index.mdx
new file mode 100644
index 0000000000000..3a694fa04fa78
--- /dev/null
+++ b/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:
+
+-
+ Agentless dependency alignment
+
+-
+ OTLP dependency alignment
+