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.traces.protocol` property

What it means

After reading the trace protocol, createSpanExporter only supports 'grpc' and 'http/protobuf'. Any other value yields IllegalArgumentException('Unsupported OTLP protocol %s specified...'). This guards against typos and unsupported exporters like the removed http/json (thrift) protocol.

Source

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

                    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)) {
                    return createHttpSpanExporter(exporterRuntimeConfig, vertx, baseUri, protocol,
                            tlsConfigurationRegistry);
                }

                throw new IllegalArgumentException(String.format("Unsupported OTLP protocol %s specified. " +
                        "Please check `quarkus.otel.exporter.otlp.traces.protocol` property", protocol));
            }

            private SpanExporter createOtlpGrpcSpanExporter(OtlpExporterRuntimeConfig exporterRuntimeConfig,
                    Vertx vertx, final URI baseUri,
                    TlsConfigurationRegistry tlsConfigurationRegistry) {

                OtlpExporterTracesConfig tracesConfig = exporterRuntimeConfig.traces();
                MemoryMode memoryMode = exporterRuntimeConfig.memoryMode();

                return new VertxGrpcSpanExporter(new GrpcExporter(
                        new VertxGrpcSender(
                                baseUri,
                                VertxGrpcSender.GRPC_TRACE_SERVICE_NAME,
                                determineCompression(tracesConfig),
                                tracesConfig.timeout(),
                                populateTracingExportHttpHeaders(tracesConfig),
                                new HttpClientOptionsConsumer(tracesConfig, baseUri, tlsConfigurationRegistry),

View on GitHub (pinned to e1c734241f)

Solutions

Set protocol to exactly grpc or http/protobuf (lowercase)
Replace deprecated http/json or http/thrift protocols — not supported by the OTLP exporter here
Check the collector endpoint matches the chosen protocol port (4317 grpc, 4318 http)

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try {
    startApplication();
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unsupported OTLP protocol")) {
        LOG.error("Use grpc or http/protobuf for quarkus.otel.exporter.otlp.traces.protocol");
    }
    throw e;
}

Prevention

Use only lowercase grpc or http/protobuf values
Do not use removed protocols like http/json or http/thrift
Match the collector port to the protocol (4317 vs 4318)
Add config validation to CI to catch typos like GRPC

When it happens

Trigger: quarkus.otel.exporter.otlp.traces.protocol set to e.g. http/json, http/thrift, GRPC (wrong case), or any string other than grpc|http/protobuf.

Common situations: Following older OpenTelemetry docs/blogs recommending http/json or http/thrift; case-sensitive typo 'GRPC'; copy-pasting protocol values from non-Quarkus OTel setups.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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