quarkusio/quarkus · error · IllegalStateException

Unable to install OTLP Exporter

Error message

Unable to install OTLP Exporter

What it means

OTelExporterRecorder wraps span exporter creation in a try/catch for IllegalArgumentException and rethrows as IllegalStateException('Unable to install OTLP Exporter'). It means configuration of the OTLP trace exporter failed — most often an invalid baseUri (non-URI or bad endpoint), unsupported protocol, or invalid TLS config — during Quarkus startup, so tracing cannot be initialized.

Source

Thrown at extensions/opentelemetry/runtime/src/main/java/io/quarkus/opentelemetry/runtime/exporter/otlp/OTelExporterRecorder.java:102

            Supplier<Vertx> vertx) {
        URI baseUri = getTracesUri(exporterRuntimeConfig.getValue()); // do the creation and validation here in order to preserve backward compatibility
        return new Function<>() {
            @Override
            public SpanExporter apply(
                    SyntheticCreationalContext<SpanExporter> context) {
                if (runtimeConfig.getValue().sdkDisabled() || baseUri == null) {
                    return SpanExporter.composite();
                }

                try {
                    TlsConfigurationRegistry tlsConfigurationRegistry = context
                            .getInjectedReference(TlsConfigurationRegistry.class);

                    return createSpanExporter(exporterRuntimeConfig.getValue(), vertx.get(), baseUri,
                            tlsConfigurationRegistry);

                } catch (IllegalArgumentException iae) {
                    throw new IllegalStateException("Unable to install OTLP Exporter", iae);
                }
            }

            private SpanExporter createSpanExporter(OtlpExporterRuntimeConfig exporterRuntimeConfig,
                    Vertx vertx,
                    URI baseUri,
                    TlsConfigurationRegistry tlsConfigurationRegistry) {
                OtlpExporterTracesConfig tracesConfig = exporterRuntimeConfig.traces();
                if (tracesConfig.protocol().isEmpty()) {
                    throw new IllegalStateException("No OTLP protocol specified. " +
                            "Please check `quarkus.otel.exporter.otlp.traces.protocol` property");
                }

                String protocol = tracesConfig.protocol().get();
                if (GRPC.equals(protocol)) {
                    return createOtlpGrpcSpanExporter(exporterRuntimeConfig, vertx, baseUri,
                            tlsConfigurationRegistry);
                } else if (HTTP_PROTOBUF.equals(protocol)) {

View on GitHub (pinned to e1c734241f)

Solutions

  1. Fix quarkus.otel.exporter.otlp.traces.endpoint to a valid absolute URI like http://localhost:4317
  2. Check the nested 'caused by' IllegalArgumentException for the exact config problem
  3. Verify quarkus.otel.exporter.otlp.traces.protocol is one of grpc|http/protobuf
  4. Validate TLS config (quarkus.otel.exporter.otlp.traces.key-manager/cert/trust-cert) points to existing files

Example fix

// before
quarkus.otel.exporter.otlp.traces.endpoint=localhost:4317
// after
quarkus.otel.exporter.otlp.traces.endpoint=http://localhost:4317
Defensive patterns

Strategy: validation

Validate before calling

// validate OTLP trace config before startup
String endpoint = ConfigProvider.getConfig()
    .getValue("quarkus.otel.exporter.otlp.traces.endpoint", String.class);
URI uri = URI.create(endpoint); // throws IllegalArgumentException early if invalid
if (uri.getScheme() == null || uri.getHost() == null) {
    throw new IllegalArgumentException("quarkus.otel.exporter.otlp.traces.endpoint must be an absolute URI: " + endpoint);
}

Type guard

static boolean isValidOtlpEndpoint(String endpoint) {
    try {
        URI uri = URI.create(endpoint);
        return uri.getScheme() != null && uri.getHost() != null;
    } catch (IllegalArgumentException | NullPointerException e) {
        return false;
    }
}

Try / catch

try {
    startApplication();
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unable to install OTLP Exporter")) {
        LOG.error("Fix quarkus.otel.exporter.otlp.traces.* properties; cause: " + e.getCause(), e);
    }
    throw e;
}

Prevention

When it happens

Trigger: quarkus.otel.exporter.otlp.traces.endpoint set to an invalid/unparseable URI, unsupported protocol value, or bad TLS/keystore configuration, causing createSpanExporter to throw IllegalArgumentException during static init / runtime recorder execution.

Common situations: Typo in the endpoint property (e.g. missing scheme, spaces), using http/protobuf vs grpc protocol mismatch, invalid TLS registry reference, or migrating property names across Quarkus versions so the resolved value is malformed.

Related errors

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