quarkusio/quarkus · error · IllegalArgumentException

Unsupported OTLP protocol %s specified. Please check `quarku

Error message

Unsupported OTLP protocol %s specified. Please check `quarkus.otel.exporter.otlp.metrics.protocol` property

What it means

When the OpenTelemetry metrics exporter is created, Quarkus checks the `quarkus.otel.exporter.otlp.metrics.protocol` value against the supported protocols. Only `grpc` and `http/protobuf` are supported; any other value makes the recorder throw an IllegalArgumentException, which is immediately wrapped into 'Unable to install OTLP Exporter' IllegalStateException. This fails fast during OTel setup so no exporter is installed with a broken protocol.

Source

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

                                                StandardComponentId.ExporterType.OTLP_HTTP_METRIC_EXPORTER),
                                        new VertxHttpSender(
                                                baseUri,
                                                VertxHttpSender.METRICS_PATH,
                                                determineCompression(metricsConfig),
                                                metricsConfig.timeout(),
                                                populateTracingExportHttpHeaders(metricsConfig),
                                                exportAsJson ? "application/json" : "application/x-protobuf",
                                                new HttpClientOptionsConsumer(metricsConfig, baseUri, tlsConfigurationRegistry),
                                                vertx.get()),
                                        MeterProvider::noop,
                                        InternalTelemetryVersion.LATEST,
                                        baseUri,
                                        false),
                                aggregationTemporalityResolver(metricsConfig),
                                aggregationResolver(metricsConfig),
                                memoryMode);
                    } else {
                        throw new IllegalArgumentException(String.format("Unsupported OTLP protocol %s specified. " +
                                "Please check `quarkus.otel.exporter.otlp.metrics.protocol` property", protocol));
                    }

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

    public Function<SyntheticCreationalContext<LogRecordExporter>, LogRecordExporter> createLogRecordExporter(
            Supplier<Vertx> vertx) {
        final URI baseUri = getLogsUri(exporterRuntimeConfig.getValue());

        return new Function<>() {
            @Override
            public LogRecordExporter apply(SyntheticCreationalContext<LogRecordExporter> context) {

View on GitHub (pinned to e1c734241f)

Solutions

Set `quarkus.otel.exporter.otlp.metrics.protocol=http/protobuf` (recommended default)
Or set it to `grpc` if using the gRPC exporter
Check for typos and case; allowed values are exactly `grpc` and `http/protobuf`
If you don't need OTLP metrics, disable the exporter (`quarkus.otel.metrics.enabled=false`) rather than leaving a broken protocol

Example fix

# before
quarkus.otel.exporter.otlp.metrics.protocol=http/json
# after
quarkus.otel.exporter.otlp.metrics.protocol=http/protobuf

Defensive patterns

Strategy: validation

Validate before calling

String p = ConfigProvider.getConfig().getValue("quarkus.otel.exporter.otlp.metrics.protocol", String.class);
if (!"grpc".equals(p) && !"http/protobuf".equals(p)) {
    throw new IllegalArgumentException("quarkus.otel.exporter.otlp.metrics.protocol must be grpc or http/protobuf, got: " + p);
}

Type guard

static boolean isSupportedOtlpProtocol(String p) {
    return "grpc".equals(p) || "http/protobuf".equals(p);
}

Try / catch

try {
    // trigger OTel init / app startup
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Unable to install OTLP Exporter")) {
        LOG.error("Fix quarkus.otel.exporter.otlp.metrics.protocol (grpc | http/protobuf)", e);
    }
}

Prevention

Only use `grpc` or `http/protobuf` — the documented supported values
Never copy `http/json` from generic OTel docs into Quarkus config
Add a startup smoke test that boots the app with production config
Keep exporter config in one profile-tested property block

When it happens

Trigger: Setting `quarkus.otel.exporter.otlp.metrics.protocol` to a value other than `grpc` or `http/protobuf` (e.g. `http/json`, `https`, `otlp`, or a typo like `htt/protobuf`) while OTLP metrics export is enabled.

Common situations: Copying config from OTel Collector docs that mention `http/json`; typos in application.properties; values that look valid in other OTel SDKs; environment-specific config drift between dev and prod.

Related errors

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