apache/cassandra · error · IllegalStateException

Unable to compute ceiling for max when histogram overflowed

Error message

Unable to compute ceiling for max when histogram overflowed

What it means

rawMean() computes the mean over non-overflow buckets. If any value exceeded the largest bucket threshold (last bucket count > 0), the true sum is unknown and the method throws IllegalStateException rather than return a wrong mean.

Solutions

Increase the histogram's bucket range at construction so realistic values fit below the max bucket
Check the overflow state before calling mean/rawMean and handle the overflow case explicitly
Aggregate or clamp extreme values at record time if they are not meaningful to measure

Example fix

// before
double m = histogram.mean(); // throws when overflowed
// after
if (!histogram.isOverflowed()) {
    double m = histogram.mean();
} else {
    // skip or alert on overflow
}

Defensive patterns

Strategy: validation

Validate before calling

Double safeMean(EstimatedHistogram h) {
    return h.isOverflowed() ? null : h.mean();
}

Try / catch

try {
    double m = histogram.mean();
} catch (IllegalStateException e) {
    // overflowed samples present: mean undefined
}

Prevention

Check overflow before computing mean
Use bucket ranges that accommodate worst-case values (e.g. long GC pauses)
Clamp or route extreme samples to a separate histogram

When it happens

Trigger: Calling rawMean()/mean() on an EstimatedHistogram where at least one sample overflowed into the last bucket.

Common situations: Requesting mean latency/duration after pathological outliers (very long GC pauses, request durations above the histogram max), or using a histogram sized for one metric with another's data.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/3ea020291693f693. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/utils/EstimatedHistogram.java:262

    /**
     * @return the ceil of mean histogram value (average of bucket offsets, weighted by count)
     * @throws IllegalStateException if any values were greater than the largest bucket threshold
     */
    public long mean()
    {
        return (long) Math.ceil(rawMean());
    }

    /**
     * @return the mean histogram value (average of bucket offsets, weighted by count)
     * @throws IllegalStateException if any values were greater than the largest bucket threshold
     */
    public double rawMean()
    {
        int lastBucket = buckets.length() - 1;
        if (buckets.get(lastBucket) > 0)
            throw new IllegalStateException("Unable to compute ceiling for max when histogram overflowed");

        long elements = 0;
        long sum = 0;
        for (int i = 0; i < lastBucket; i++)
        {
            long bCount = buckets.get(i);
            elements += bCount;
            sum += bCount * bucketOffsets[i];
        }

        if (elements == 0)
            return 0.0D;
        return (double) sum / elements;
    }

    /**
     * @return the total number of non-zero values
     */

View on GitHub (pinned to 88fd0f6a0e)