apache/cassandra · error · IllegalArgumentException

Illegal capacity

Error message

Illegal capacity ${requestedCapacity}

What it means

StreamingTombstoneHistogramBuilder.Spool validates its requestedCapacity and throws IllegalArgumentException when it is negative. The spool backs the histogram's sampling phase and cannot allocate a negative-capacity structure.

Solutions

1. Pass a positive capacity: check requestedCapacity >= 0 before constructing and clamp to a sensible minimum (e.g. Math.max(1, capacity)).
2. Fix the computation producing the negative value (often a subtraction or bad config-derived parameter).
3. If capacity 0 is intended, note the check is < 0, so 0 is accepted; negative values indicate a caller bug.

Example fix

// before
new StreamingTombstoneHistogramBuilder(zeroTime, roundSeconds, maxBinSize, volumeType, capacity);
// after
int safeCapacity = Math.max(1, capacity);
new StreamingTombstoneHistogramBuilder(zeroTime, roundSeconds, maxBinSize, volumeType, safeCapacity);

if (capacity < 0) throw new IllegalArgumentException("capacity must be >= 0, got " + capacity);

When it happens

Trigger: Constructing StreamingTombstoneHistogramBuilder (or otherwise instantiating the internal Spool) with requestedCapacity < 0, usually from a computed value like maxBinSize or a band parameter that underflowed.

Common situations: Hand-tuned cassandra.yaml histogram settings (e.g. tombstone_warn_threshold / histogram bin sizes) producing negative derived capacities; integer underflow in calling code.

Related errors

• A CounterId representation is exactly
• Invalid version value
• Only single character delimiters supported, was
• Reader index should be non-negative, but was
• Size must be non-negative

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

Appendix: source

Thrown at src/java/org/apache/cassandra/utils/streamhist/StreamingTombstoneHistogramBuilder.java:428

    /**
     * This class is a specialized open addressing HashMap that uses int as keys and int as values.
     * This is an optimization to avoid allocating objects.
     * In order for this class to work correctly it should have a power of 2 capacity.
     * This last invariant is taken care of during construction.
     */
    static class Spool
    {
        final long[] points;
        final int[] values;

        final int capacity;
        int size;

        Spool(int requestedCapacity)
        {
            if (requestedCapacity < 0)
                throw new IllegalArgumentException("Illegal capacity " + requestedCapacity);

            this.capacity = getPowerOfTwoCapacity(requestedCapacity);

            // x2 because we want no more than two reprobes on average when _capacity_ entries will be written
            points = new long[capacity * 2];
            values = new int[capacity * 2];
            clear();
        }

        private int getPowerOfTwoCapacity(int requestedCapacity)
        {
            //for spool we need power-of-two cells
            return requestedCapacity == 0 ? 0 : IntMath.pow(2, IntMath.log2(requestedCapacity, RoundingMode.CEILING));
        }

        void clear()
        {
            Arrays.fill(points, -1);

View on GitHub (pinned to 88fd0f6a0e)