apache/skywalking · error · IllegalArgumentException

Incompatible BucketedValues [{value}] for current Percentile

Error message

Incompatible BucketedValues [{value}] for current PercentileFunction[{summation}]

What it means

SumHistogramPercentileFunction aggregates MAL `sum_histogram_percentile` metrics. Once it has accepted a BucketedValues set, its `summation` bucket layout (bucket count and each bucket's min boundary) is fixed; BucketedValues.isCompatible(summation) returns false when a new input's histogram buckets do not match that layout, and this IllegalArgumentException rejects the input.

Source

Thrown at oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/meter/function/sum/SumHistogramPercentileFunction.java:100

    @ElasticSearch.Column(legacyName = "summation")
    @BanyanDB.MeasureField
    protected DataTable summation = new DataTable(30);
    /**
     * Rank
     */
    @Getter
    @Setter
    @Column(name = RANKS, storageOnly = true)
    @BanyanDB.MeasureField
    private IntList ranks = new IntList(10);

    private boolean isCalculated = false;

    @Override
    public void accept(final MeterEntity entity, final PercentileArgument value) {
        if (summation.size() > 0) {
            if (!value.getBucketedValues().isCompatible(summation)) {
                throw new IllegalArgumentException(
                    "Incompatible BucketedValues [" + value + "] for current PercentileFunction[" + summation + "]");
            }
        }

        for (final int rank : value.getRanks()) {
            if (rank <= 0) {
                throw new IllegalArgumentException("Illegal rank value " + rank + ", must be positive");
            }
        }

        if (ranks.size() > 0) {
            if (ranks.size() != value.getRanks().length) {
                throw new IllegalArgumentException(
                    "Incompatible ranks size = [" + value.getRanks().length + "] for current PercentileFunction[" + ranks
                        .size() + "]");
            } else {
                for (final int rank : value.getRanks()) {
                    if (!ranks.include(rank)) {

View on GitHub (pinned to 102af09b4a)

Solutions

Align the bucket definitions of every MAL rule producing this metric: same number of `bucket` entries, same values, same `bucketMin` and alignment
Restart all OAP nodes (or wait for window rollover) after changing bucket config so the new layout is locked consistently
Give differently-bucketed metrics distinct metric names instead of reusing one name

Example fix

# before — rule A and rule B disagree
histogram(step1: 100, ...)
histogram(step1: 50, ...)
# after — both rules use the identical bucket list
histogram(step1: 100, step2: 200, step3: 400, ...)

Defensive patterns

Strategy: validation

Validate before calling

// verify bucket layout matches before accept()
if (function.getSummation().size() > 0 && !argument.getBucketedValues().isCompatible(function.getSummation())) {
    log.warn("Bucket layout mismatch for {}; dropping sample", metricName);
    return;
}
function.accept(entity, argument);

Try / catch

Wrap only the accept() call in try-catch (IllegalArgumentException), log the offending BucketedValues and the locked summation layout, and skip the sample so other metrics in the same batch still process.

Prevention

Define bucket thresholds once (YAML anchor or shared include) and reuse across all rules for a metric
Coordinate OAP restarts when changing histogram bucket config
Use distinct metric names when bucket layouts must genuinely differ

When it happens

Trigger: The same sum_histogram_percentile metric receives, in one time window, two inputs with different `bucket` steps, different numbers of buckets, or different `bucketMin`/`bucketAlgo` in the MAL histogram() expression (e.g. one rule uses buckets of 100ms and another of 50ms for latency).

Common situations: Changing latency bucket thresholds in an otel-rules or meter-analyzer-config YAML and redeploying agents/OAP nodes gradually; two services reporting the same metric name with differently configured agents; copy-pasting a MAL rule and editing only the buckets.

Related errors

AI-assisted analysis of apache/skywalking@102af09b4a (2026-08-14). Data as JSON: /api/errors/cf490e0e5c86774b. Report an issue: GitHub.