quarkusio/quarkus · error · VertxException

OpenTelemetryContextUnwrapper was not found

Error message

OpenTelemetryContextUnwrapper was not found

What it means

Vert.x 4.5+ passes an OpenTelemetryContextUnwrapper to createHttpServerMetrics so HTTP server metrics can bridge into OpenTelemetry context. VertxMeterBinderAdapter requires this collaborator whenever it builds VertxHttpServerMetrics; if it is null (the OpenTelemetry bridge class/bean not available) the adapter throws VertxException instead of creating metrics without OTel support.

Source

Thrown at extensions/micrometer/runtime/src/main/java/io/quarkus/micrometer/runtime/binder/vertx/VertxMeterBinderAdapter.java:75

    @Override
    public VertxMetrics metrics(VertxOptions vertxOptions) {
        return this;
    }

    @Override
    public MetricsOptions newOptions() {
        return this;
    }

    @Override
    public HttpServerMetrics<?, ?> createHttpServerMetrics(final HttpServerConfig options,
            final SocketAddress tcpLocalAddress, final SocketAddress localAddress) {
        if (httpBinderConfiguration == null) {
            throw new VertxException("HttpBinderConfiguration was not found");
        }
        if (openTelemetryContextUnwrapper == null) {
            throw new VertxException("OpenTelemetryContextUnwrapper was not found");
        }
        if (httpBinderConfiguration.isServerEnabled()) {
            log.debugf("Create HttpServerMetrics with options %s and address %s", options, localAddress);
            return new VertxHttpServerMetrics(Metrics.globalRegistry, httpBinderConfiguration, openTelemetryContextUnwrapper,
                    options, longAdderGauges);
        }
        return null;
    }

    @Override
    public HttpClientMetrics<?, ?> createHttpClientMetrics(HttpClientConfig config) {
        if (httpBinderConfiguration == null) {
            return null;
        }
        if (httpBinderConfiguration.isClientEnabled()) {
            String metricsName = config.getObservabilityConfig() != null
                    ? config.getObservabilityConfig().getMetricsName()
                    : null;

View on GitHub (pinned to e1c734241f)

Solutions

1. Add quarkus-opentelemetry (and quarkus-micrometer-opentelemetry if applicable) so the OpenTelemetryContextUnwrapper is available and injected
2. Align vertx-core and quarkus-micrometer versions via the Quarkus BOM so the adapter and Vert.x agree on this API
3. If constructing the adapter manually (tests), pass/set a non-null OpenTelemetryContextUnwrapper instance before creating HTTP server metrics
4. If OTel is not wanted, use a no-op unwrapper implementation to satisfy the contract

Example fix

// before
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-micrometer</artifactId>
</dependency>
<!-- OTel unwrapper missing -> VertxException -->

// after
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-micrometer</artifactId>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-opentelemetry</artifactId>
</dependency>

if (adapter.openTelemetryContextUnwrapper == null) {
    throw new IllegalStateException("Add quarkus-opentelemetry or provide an OpenTelemetryContextUnwrapper");
}

try {
    return adapter.createHttpServerMetrics(options, tcpAddr, localAddr);
} catch (VertxException e) {
    if (e.getMessage().contains("OpenTelemetryContextUnwrapper")) {
        log.error("OpenTelemetry bridge missing; add quarkus-opentelemetry");
    }
    throw e;
}

When it happens

Trigger: Vert.x starts an HTTP server and invokes createHttpServerMetrics while openTelemetryContextUnwrapper was never set — typically because the OpenTelemetry context propagating classes are not on the classpath (opentelemetry extension absent) or the field was not initialized when the adapter was constructed manually.

Common situations: Using quarkus-micrometer without quarkus-opentelemetry where the adapter still expects the unwrapper; partial manual wiring in tests; version skew between vertx-core (which calls the new API) and the micrometer adapter built for an older Vert.x.

Related errors

• HttpBinderConfiguration was not found
• Failed to find any non-blocking provider for startup actions
• No Vert.x instance has been registered in ArC ?
• No valueExpressionResolver is defined
• Failed to instantiate {{VIRTUAL_THREAD_BINDER_CLASSNAME}}

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