apache/cassandra · error · IllegalStateException

Unable to compute when histogram overflowed

Error message

Unable to compute when histogram overflowed

What it means

EstimatedHistogram stores counts in offset buckets where the last bucket is the overflow bucket. percentile() cannot compute a percentile if any recorded value exceeded the largest bucket threshold, because the exact distribution is unknown, so it throws IllegalStateException.

Solutions

1. Construct the histogram with a larger bucket range (bigger offsets/max value) so expected values never overflow
2. Check isOverflowed()/the last bucket before calling percentile and skip or report overflow instead
3. For mean-like needs, use the overflow-aware alternatives where available rather than rawMean/percentile

Example fix

// before
EstimatedHistogram h = new EstimatedHistogram(); // default range
long p = h.percentile(0.99); // throws if overflowed
// after
if (!h.isOverflowed()) {
    long p = h.percentile(0.99);
} else {
    // handle overflow: report 'unknown'/create larger histogram
}

long safePercentile(EstimatedHistogram h, double p) {
    return h.isOverflowed() ? -1 : h.percentile(p); // -1 signals overflow
}

try {
    long v = histogram.percentile(0.99);
} catch (IllegalStateException e) {
    // histogram overflowed: report unknown / use larger histogram
}

When it happens

Trigger: Calling percentile(...) (or data/mean paths through it) after at least one recorded value landed in the last (overflow) bucket, i.e. buckets.get(lastBucket) > 0.

Common situations: Latency histograms with extreme outliers exceeding the max bucket (default ~hours for latency histograms), long-running nodes with huge record latencies, or requesting percentiles from an inappropriately sized histogram.

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

• Unable to compute ceiling for max when histogram overflowed
• Illegal capacity
• ${value}
• A CounterId representation is exactly
• a hints file cannot be configured for both compression and…

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

Appendix: source

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

        for (int i = lastBucket - 1; i >= 0; i--)
        {
            if (buckets.get(i) > 0)
                return bucketOffsets[i];
        }
        return 0;
    }

    /**
     * @param percentile
     * @return estimated value at given percentile
     */
    public long percentile(double percentile)
    {
        assert percentile >= 0 && percentile <= 1.0;
        int lastBucket = buckets.length() - 1;
        if (buckets.get(lastBucket) > 0)
            throw new IllegalStateException("Unable to compute when histogram overflowed");

        long pcount = (long) Math.ceil(count() * percentile);
        if (pcount == 0)
            return 0;

        long elements = 0;
        for (int i = 0; i < lastBucket; i++)
        {
            elements += buckets.get(i);
            if (elements >= pcount)
                return bucketOffsets[i];
        }
        return 0;
    }

    /**
     * @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

View on GitHub (pinned to 88fd0f6a0e)