What causes "Unrecognized default histogram aggregation: " in quarkusio/quarkus?

Set the value to `explicit_buckets_histogram`

quarkusio/quarkus · error · ConfigurationException

Unrecognized default histogram aggregation:

Error message

Unrecognized default histogram aggregation:

What it means

`quarkus.otel.exporter.otlp.metrics.default_histogram_aggregation` accepts only `explicit_buckets_histogram` and `exponential_bucket_histogram`. Any other value makes `aggregationResolver` throw a ConfigurationException naming the bad value. This determines the SDK's default aggregation for histogram instruments.

Source

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

        };
    }

    private static DefaultAggregationSelector aggregationResolver(OtlpExporterMetricsConfig metricsConfig) {
        String defaultHistogramAggregation = metricsConfig.defaultHistogramAggregation()
                .map(s -> s.toLowerCase(Locale.ROOT))
                .orElse("explicit_bucket_histogram");

        DefaultAggregationSelector aggregationSelector;
        if (defaultHistogramAggregation.equals("explicit_bucket_histogram")) {
            aggregationSelector = DefaultAggregationSelector.getDefault();
        } else if (BASE2EXPONENTIAL_AGGREGATION_NAME.equalsIgnoreCase(defaultHistogramAggregation)) {

            aggregationSelector = DefaultAggregationSelector
                    .getDefault()
                    .with(InstrumentType.HISTOGRAM, Aggregation.base2ExponentialBucketHistogram());

        } else {
            throw new ConfigurationException(
                    "Unrecognized default histogram aggregation: " + defaultHistogramAggregation);
        }
        return aggregationSelector;
    }

    private static AggregationTemporalitySelector aggregationTemporalityResolver(OtlpExporterMetricsConfig metricsConfig) {
        String temporalityValue = metricsConfig.temporalityPreference()
                .map(s -> s.toLowerCase(Locale.ROOT))
                .orElse("cumulative");
        AggregationTemporalitySelector temporalitySelector = switch (temporalityValue) {
            case "cumulative" -> AggregationTemporalitySelector.alwaysCumulative();
            case "delta" -> AggregationTemporalitySelector.deltaPreferred();
            case "lowmemory" -> AggregationTemporalitySelector.lowMemory();
            default -> throw new ConfigurationException("Unrecognized aggregation temporality: " + temporalityValue);
        };
        return temporalitySelector;
    }

View on GitHub (pinned to e1c734241f)

Solutions

Set the value to `explicit_buckets_histogram`
Or set it to `exponential_bucket_histogram`
Check spelling; the message after the colon shows exactly what value was rejected
Remove the property to use the SDK default

Example fix

# before
quarkus.otel.exporter.otlp.metrics.default_histogram_aggregation=exponential
# after
quarkus.otel.exporter.otlp.metrics.default_histogram_aggregation=exponential_bucket_histogram

Defensive patterns

Strategy: validation

Validate before calling

String a = ConfigProvider.getConfig().getValue("quarkus.otel.exporter.otlp.metrics.default_histogram_aggregation", String.class);
if (!java.util.List.of("explicit_buckets_histogram", "exponential_bucket_histogram").contains(a)) {
    throw new IllegalArgumentException("Invalid default_histogram_aggregation: " + a);
}

Type guard

static boolean isSupportedHistogramAggregation(String a) {
    return "explicit_buckets_histogram".equals(a) || "exponential_bucket_histogram".equals(a);
}

Try / catch

try {
    app.start();
} catch (RuntimeException e) {
    if (String.valueOf(e.getMessage()).startsWith("Unrecognized default histogram aggregation")) {
        LOG.error("Use explicit_buckets_histogram or exponential_bucket_histogram");
    }
}

Prevention

Copy values verbatim from the Quarkus OpenTelemetry config reference
Prefer removing the property and using the SDK default unless specific behavior is needed
Keep enum-valued config keys in a shared, reviewed properties template

When it happens

Trigger: Configuring `quarkus.otel.exporter.otlp.metrics.default_histogram_aggregation` with a misspelled or unsupported string (e.g. `explicit`, `exponential`, `histogram`).

Common situations: Guessing value names instead of copying from the Quarkus OTel docs; older configs written for previous SDK naming; autocomplete against non-Quarkus property names.

Related errors

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