From 8a8c891609ab5c81f7b4441e6457d404a7d1a5d1 Mon Sep 17 00:00:00 2001 From: muxiaoming <116002422+muxiaoming@users.noreply.github.com> Date: Wed, 17 Jun 2026 18:43:13 +0800 Subject: [PATCH 1/2] docs: Add JDBC dependency conflict warning for Spring AI integration Add a warning section explaining the OpenTelemetry version conflict that occurs when using JDBC datasource with Spring AI. Includes: - Problem description and error message - Root cause analysis - Solution with XML configuration - Links to related PR and bug report Closes langfuse/langfuse-docs#3116 --- content/integrations/frameworks/spring-ai.mdx | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/content/integrations/frameworks/spring-ai.mdx b/content/integrations/frameworks/spring-ai.mdx index e16afc72e..39522213d 100644 --- a/content/integrations/frameworks/spring-ai.mdx +++ b/content/integrations/frameworks/spring-ai.mdx @@ -195,6 +195,57 @@ With these configurations and dependencies in place, your Spring Boot applicatio Each span will carry attributes like `gen_ai.operation.name`, `gen_ai.system` (the provider, e.g. “openai”), model names, token usage, etc., and – since we enabled them – events for the prompt and response content. +## ⚠️ Important: JDBC Dependency Conflict + +If your Spring AI application uses a JDBC datasource, you may encounter a dependency conflict that prevents the application from starting. This is caused by a version mismatch between OpenTelemetry libraries. + +### The Problem + +When you add JDBC dependencies (e.g., `spring-boot-starter-jdbc`), the application fails to start with an error like: + +``` +APPLICATION FAILED TO START + +An attempt was made to call a method that does not exist. + +The following method did not exist: + 'setCaptureQueryParameters(boolean)' +``` + +This happens because: + +1. `micrometer-tracing-bridge-otel` (version 1.4.4 in Spring Boot 3.4.x) has a transitive dependency on `opentelemetry-instrumentation-api-incubator:2.9.0-alpha` +2. `opentelemetry-jdbc:2.17.0-alpha` (from `opentelemetry-spring-boot-starter`) requires `opentelemetry-instrumentation-api-incubator:2.17.0-alpha` +3. Maven resolves this in favor of the older transitive dependency (2.9.0-alpha), causing the method-not-found error + +### The Solution + +Exclude the problematic transitive dependency and explicitly declare the correct version in your `pom.xml`: + +```xml + + io.micrometer + micrometer-tracing-bridge-otel + + + io.opentelemetry.instrumentation + opentelemetry-instrumentation-api-incubator + + + + + io.opentelemetry.instrumentation + opentelemetry-instrumentation-api-incubator + 2.17.0-alpha + +``` + +### Reference + +For more details, see: +- [Spring AI Demo Fix PR](https://github.com/langfuse/langfuse-examples/pull/34) +- [Related Bug Report](https://github.com/langfuse/langfuse/issues/14312) + ## Step 2: Configure Langfuse Now that your Spring AI application is emitting OpenTelemetry trace data, the next step is to direct that data to Langfuse. From b3ecefe407b8678ba356dd821964e3971fd09fe4 Mon Sep 17 00:00:00 2001 From: muxiaoming <116002422+muxiaoming@users.noreply.github.com> Date: Wed, 17 Jun 2026 18:49:23 +0800 Subject: [PATCH 2/2] fix: Remove hardcoded version and add Gradle example Address code review feedback: - Remove hardcoded version 2.17.0-alpha, let BOM manage it - Add Gradle equivalent for the workaround - Make version numbers in explanation more generic - Add note that exact versions may vary --- content/integrations/frameworks/spring-ai.mdx | 26 ++++++++++++------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/content/integrations/frameworks/spring-ai.mdx b/content/integrations/frameworks/spring-ai.mdx index 39522213d..0cd82f8b6 100644 --- a/content/integrations/frameworks/spring-ai.mdx +++ b/content/integrations/frameworks/spring-ai.mdx @@ -195,6 +195,7 @@ With these configurations and dependencies in place, your Spring Boot applicatio Each span will carry attributes like `gen_ai.operation.name`, `gen_ai.system` (the provider, e.g. “openai”), model names, token usage, etc., and – since we enabled them – events for the prompt and response content. + ## ⚠️ Important: JDBC Dependency Conflict If your Spring AI application uses a JDBC datasource, you may encounter a dependency conflict that prevents the application from starting. This is caused by a version mismatch between OpenTelemetry libraries. @@ -214,13 +215,15 @@ The following method did not exist: This happens because: -1. `micrometer-tracing-bridge-otel` (version 1.4.4 in Spring Boot 3.4.x) has a transitive dependency on `opentelemetry-instrumentation-api-incubator:2.9.0-alpha` -2. `opentelemetry-jdbc:2.17.0-alpha` (from `opentelemetry-spring-boot-starter`) requires `opentelemetry-instrumentation-api-incubator:2.17.0-alpha` -3. Maven resolves this in favor of the older transitive dependency (2.9.0-alpha), causing the method-not-found error +1. `micrometer-tracing-bridge-otel` (managed by Spring Boot) has a transitive dependency on an older `opentelemetry-instrumentation-api-incubator` version +2. `opentelemetry-jdbc` (from `opentelemetry-spring-boot-starter`) requires a newer `opentelemetry-instrumentation-api-incubator` version +3. Maven resolves this in favor of the older transitive dependency, causing the method-not-found error + +> **Note:** The exact version numbers in the error message may vary depending on your Spring Boot and OpenTelemetry versions. Look for the same `setCaptureQueryParameters` method-not-found error. ### The Solution -Exclude the problematic transitive dependency and explicitly declare the correct version in your `pom.xml`: +Exclude the problematic transitive dependency from `micrometer-tracing-bridge-otel`. Since the guide's BOM already manages `opentelemetry-instrumentation-api-incubator`, you don't need to specify a version: ```xml @@ -233,11 +236,16 @@ Exclude the problematic transitive dependency and explicitly declare the correct - - io.opentelemetry.instrumentation - opentelemetry-instrumentation-api-incubator - 2.17.0-alpha - +``` + +> **Note:** The `opentelemetry-instrumentation-bom` in your `` will automatically resolve the correct version. No explicit version declaration is needed. + +**For Gradle users:** + +```groovy +configurations.all { + exclude group: 'io.opentelemetry.instrumentation', module: 'opentelemetry-instrumentation-api-incubator' +} ``` ### Reference