{"record":{"id":"675145364ebe4498","repo":"quarkusio/quarkus","slug":"connection-otelapinotfound","errorCode":"Connection.OtelApiNotFound","errorMessage":"Connection.OtelApiNotFound","messagePattern":"Connection\\.OtelApiNotFound","errorType":"error_code","errorClass":"SQLException","httpStatus":null,"severity":"error","filePath":"extensions/jdbc/jdbc-mysql/runtime/src/main/java/io/quarkus/jdbc/mysql/runtime/graal/com/mysql/cj/jdbc/MySQLJDBCSubstitutions.java","lineNumber":81,"sourceCode":"\n}\n\n@TargetClass(className = \"com.mysql.cj.jdbc.ha.ReplicationConnectionGroupManager\")\nfinal class ReplicationConnectionGroupManager {\n\n    @Substitute\n    public static void registerJmx() throws SQLException {\n        throw new IllegalStateException(\"Not Implemented in native mode\");\n    }\n\n}\n\n@TargetClass(className = \"com.mysql.cj.otel.OpenTelemetryHandler\", onlyWith = OpenTelemetryUnavailable.class)\nfinal class OpenTelemetryHandler implements TelemetryHandler {\n\n    @Substitute\n    public OpenTelemetryHandler() {\n        throw ExceptionFactory.createException(Messages.getString(\"Connection.OtelApiNotFound\"));\n    }\n\n    @Override\n    @Substitute\n    public TelemetrySpan startSpan(TelemetrySpanName telemetrySpanName, Object... objects) {\n        return null;\n    }\n\n    @Override\n    @Substitute\n    public void addLinkTarget(TelemetrySpan span) {\n    }\n\n    @Override\n    @Substitute\n    public void removeLinkTarget(TelemetrySpan span) {\n    }\n","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/jdbc/jdbc-mysql/runtime/src/main/java/io/quarkus/jdbc/mysql/runtime/graal/com/mysql/cj/jdbc/MySQLJDBCSubstitutions.java#L63-L99","documentation":"Quarkus substitutes com.mysql.cj.otel.OpenTelemetryHandler with a stub that is active only when the OpenTelemetry API is unavailable on the classpath (onlyWith = OpenTelemetryUnavailable.class). Its constructor throws an exception built from the driver message 'Connection.OtelApiNotFound'. It means the MySQL Connector/J telemetry plumbing was invoked even though no OpenTelemetry API is present, so the driver cannot create a telemetry handler.","triggerScenarios":"Enabling MySQL Connector/J telemetry usage in native or JVM mode without io.opentelemetry:opentelemetry-api on the classpath, so the OpenTelemetryUnavailable condition holds and the stub constructor throws.","commonSituations":"Applications that set driver observability options (e.g. otel-related connection properties) without adding the OpenTelemetry dependency; native-image builds where OTel API was excluded; mismatch between quarkus-opentelemetry presence and the driver's expectations.","solutions":["Add the OpenTelemetry API dependency (io.opentelemetry:opentelemetry-api, typically via the quarkus-opentelemetry extension) so the real TelemetryHandler is used.","Remove OpenTelemetry-related connection properties from the JDBC URL if you do not intend to use tracing.","Ensure quarkus-opentelemetry is configured when datasource tracing is enabled in application.properties.","Update the MySQL JDBC driver/extension versions so telemetry negotiation matches the installed OTel API."],"exampleFix":"// before: pom.xml lacks OTel but JDBC URL enables it\njdbc:mysql://host/db?otelEnabled=true\n// after: add quarkus-opentelemetry\ndependency: io.quarkus:quarkus-opentelemetry","handlingStrategy":"validation","validationCode":"Class.forName(\"io.opentelemetry.api.trace.Tracer\");\n// throws ClassNotFoundException early if the OpenTelemetry API dependency is missing","typeGuard":null,"tryCatchPattern":"try {\n    TelemetryHandler h = new OpenTelemetryHandler();\n} catch (SQLException e) {\n    if (e.getMessage().contains(\"OtelApiNotFound\")) {\n        log.warn(\"OpenTelemetry API missing; disabling driver telemetry\");\n        h = NoopTelemetryHandler.INSTANCE;\n    } else { throw e; }\n}","preventionTips":["Add io.quarkus:quarkus-opentelemetry whenever JDBC tracing is enabled","Remove otel-related properties from the JDBC URL when OTel is not on the classpath","Add a startup check that validates the OTel API is present when tracing config is enabled"],"tags":["mysql","opentelemetry","missing-dependency","tracing"],"backgroundTag":"missing-dependency","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}