quarkusio/quarkus · error · SQLException

Connection.OtelApiNotFound

Connection.OtelApiNotFound

Error message

Connection.OtelApiNotFound

What it means

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.

Source

Thrown at extensions/jdbc/jdbc-mysql/runtime/src/main/java/io/quarkus/jdbc/mysql/runtime/graal/com/mysql/cj/jdbc/MySQLJDBCSubstitutions.java:81

}

@TargetClass(className = "com.mysql.cj.jdbc.ha.ReplicationConnectionGroupManager")
final class ReplicationConnectionGroupManager {

    @Substitute
    public static void registerJmx() throws SQLException {
        throw new IllegalStateException("Not Implemented in native mode");
    }

}

@TargetClass(className = "com.mysql.cj.otel.OpenTelemetryHandler", onlyWith = OpenTelemetryUnavailable.class)
final class OpenTelemetryHandler implements TelemetryHandler {

    @Substitute
    public OpenTelemetryHandler() {
        throw ExceptionFactory.createException(Messages.getString("Connection.OtelApiNotFound"));
    }

    @Override
    @Substitute
    public TelemetrySpan startSpan(TelemetrySpanName telemetrySpanName, Object... objects) {
        return null;
    }

    @Override
    @Substitute
    public void addLinkTarget(TelemetrySpan span) {
    }

    @Override
    @Substitute
    public void removeLinkTarget(TelemetrySpan span) {
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the OpenTelemetry API dependency (io.opentelemetry:opentelemetry-api, typically via the quarkus-opentelemetry extension) so the real TelemetryHandler is used.
2. Remove OpenTelemetry-related connection properties from the JDBC URL if you do not intend to use tracing.
3. Ensure quarkus-opentelemetry is configured when datasource tracing is enabled in application.properties.
4. Update the MySQL JDBC driver/extension versions so telemetry negotiation matches the installed OTel API.

Example fix

// before: pom.xml lacks OTel but JDBC URL enables it
jdbc:mysql://host/db?otelEnabled=true
// after: add quarkus-opentelemetry
dependency: io.quarkus:quarkus-opentelemetry

Class.forName("io.opentelemetry.api.trace.Tracer");
// throws ClassNotFoundException early if the OpenTelemetry API dependency is missing

try {
    TelemetryHandler h = new OpenTelemetryHandler();
} catch (SQLException e) {
    if (e.getMessage().contains("OtelApiNotFound")) {
        log.warn("OpenTelemetry API missing; disabling driver telemetry");
        h = NoopTelemetryHandler.INSTANCE;
    } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• The Vert.x Context is not set
• The OpenTelemetry Context is not set
• dummy
• Assistant not available
• Failed to find any non-blocking provider for startup actions

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/675145364ebe4498. Report an issue: GitHub.