{"record":{"id":"ccb13a3672cb5154","repo":"quarkusio/quarkus","slug":"unable-to-install-otlp-exporter","errorCode":null,"errorMessage":"Unable to install OTLP Exporter","messagePattern":"Unable to install OTLP Exporter","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/opentelemetry/runtime/src/main/java/io/quarkus/opentelemetry/runtime/exporter/otlp/OTelExporterRecorder.java","lineNumber":102,"sourceCode":"            Supplier<Vertx> vertx) {\n        URI baseUri = getTracesUri(exporterRuntimeConfig.getValue()); // do the creation and validation here in order to preserve backward compatibility\n        return new Function<>() {\n            @Override\n            public SpanExporter apply(\n                    SyntheticCreationalContext<SpanExporter> context) {\n                if (runtimeConfig.getValue().sdkDisabled() || baseUri == null) {\n                    return SpanExporter.composite();\n                }\n\n                try {\n                    TlsConfigurationRegistry tlsConfigurationRegistry = context\n                            .getInjectedReference(TlsConfigurationRegistry.class);\n\n                    return createSpanExporter(exporterRuntimeConfig.getValue(), vertx.get(), baseUri,\n                            tlsConfigurationRegistry);\n\n                } catch (IllegalArgumentException iae) {\n                    throw new IllegalStateException(\"Unable to install OTLP Exporter\", iae);\n                }\n            }\n\n            private SpanExporter createSpanExporter(OtlpExporterRuntimeConfig exporterRuntimeConfig,\n                    Vertx vertx,\n                    URI baseUri,\n                    TlsConfigurationRegistry tlsConfigurationRegistry) {\n                OtlpExporterTracesConfig tracesConfig = exporterRuntimeConfig.traces();\n                if (tracesConfig.protocol().isEmpty()) {\n                    throw new IllegalStateException(\"No OTLP protocol specified. \" +\n                            \"Please check `quarkus.otel.exporter.otlp.traces.protocol` property\");\n                }\n\n                String protocol = tracesConfig.protocol().get();\n                if (GRPC.equals(protocol)) {\n                    return createOtlpGrpcSpanExporter(exporterRuntimeConfig, vertx, baseUri,\n                            tlsConfigurationRegistry);\n                } else if (HTTP_PROTOBUF.equals(protocol)) {","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/opentelemetry/runtime/src/main/java/io/quarkus/opentelemetry/runtime/exporter/otlp/OTelExporterRecorder.java#L84-L120","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix quarkus.otel.exporter.otlp.traces.endpoint to a valid absolute URI like http://localhost:4317","Check the nested 'caused by' IllegalArgumentException for the exact config problem","Verify quarkus.otel.exporter.otlp.traces.protocol is one of grpc|http/protobuf","Validate TLS config (quarkus.otel.exporter.otlp.traces.key-manager/cert/trust-cert) points to existing files"],"exampleFix":"// before\nquarkus.otel.exporter.otlp.traces.endpoint=localhost:4317\n// after\nquarkus.otel.exporter.otlp.traces.endpoint=http://localhost:4317","handlingStrategy":"validation","validationCode":"// validate OTLP trace config before startup\nString endpoint = ConfigProvider.getConfig()\n    .getValue(\"quarkus.otel.exporter.otlp.traces.endpoint\", String.class);\nURI uri = URI.create(endpoint); // throws IllegalArgumentException early if invalid\nif (uri.getScheme() == null || uri.getHost() == null) {\n    throw new IllegalArgumentException(\"quarkus.otel.exporter.otlp.traces.endpoint must be an absolute URI: \" + endpoint);\n}","typeGuard":"static boolean isValidOtlpEndpoint(String endpoint) {\n    try {\n        URI uri = URI.create(endpoint);\n        return uri.getScheme() != null && uri.getHost() != null;\n    } catch (IllegalArgumentException | NullPointerException e) {\n        return false;\n    }\n}","tryCatchPattern":"try {\n    startApplication();\n} catch (IllegalStateException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Unable to install OTLP Exporter\")) {\n        LOG.error(\"Fix quarkus.otel.exporter.otlp.traces.* properties; cause: \" + e.getCause(), e);\n    }\n    throw e;\n}","preventionTips":["Always use absolute URIs with scheme for the OTLP endpoint","Keep protocol and endpoint consistent (4317/grpc, 4318/http/protobuf)","Read the caused-by IllegalArgumentException for the root config error","Validate OTLP config in CI before deploying"],"tags":["opentelemetry","otlp","config","startup"],"backgroundTag":"invalid-exporter-endpoint","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}