aeron-io/aeron · error · IllegalArgumentException

initialCapacity outside range 0

Error message

initialCapacity outside range 0 - <MAX_CAPACITY>: initialCapacity=<initialCapacity>

What it means

BufferBuilder's constructor validates initialCapacity against [0, MAX_CAPACITY] and throws IllegalArgumentException when it is negative or exceeds the maximum. BufferBuilder backs its data with a single bounded buffer, so an oversized initial capacity cannot be honored.

Solutions

1. Clamp initialCapacity to [0, MAX_CAPACITY] before constructing: Math.max(0, Math.min(value, BufferBuilder.MAX_CAPACITY)).
2. Fix the source of the bad value (config parsing, overflow-prone arithmetic).
3. Rely on the default constructor or BufferBuilder's auto-resizing instead of a huge initial capacity — it grows as needed.

Example fix

// before
BufferBuilder b = new BufferBuilder(cfg, true);
// after
int capped = Math.max(0, Math.min(cfg, BufferBuilder.MAX_CAPACITY));
BufferBuilder b = new BufferBuilder(capped, true);

int capped = Math.max(0, Math.min(initialCapacity, BufferBuilder.MAX_CAPACITY));
BufferBuilder b = new BufferBuilder(capped, isDirect);

try {
    builder = new BufferBuilder(initialCapacity, true);
} catch (IllegalArgumentException e) {
    builder = new BufferBuilder(); // fall back to defaults
}

When it happens

Trigger: new BufferBuilder(negativeValue, ...) or initialCapacity greater than MAX_CAPACITY (Integer.MAX_VALUE-derived cap) — typically from a bad constant, misconfigured setting, or overflowed computation.

Common situations: Passing a config value read from properties/env without clamping; computing initial capacity from a length/2x-doubling arithmetic that overflowed; copying a capacity from another, larger buffer.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• limit outside range: capacity=
• counter id is negative
• counter id out of range: 0 - maxCounterId=
• counter id is not allocated, state
• insufficient capacity: maxCapacity=

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/046acb1424cd1e4b. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/BufferBuilder.java:82

     *
     * @param initialCapacity at which the capacity will start.
     */
    public BufferBuilder(final int initialCapacity)
    {
        this(initialCapacity, false);
    }

    /**
     * Construct a buffer builder with an initial capacity.
     *
     * @param initialCapacity at which the capacity will start.
     * @param isDirect        is the underlying buffer to be a direct {@link ByteBuffer}
     */
    public BufferBuilder(final int initialCapacity, final boolean isDirect)
    {
        if (initialCapacity < 0 || initialCapacity > MAX_CAPACITY)
        {
            throw new IllegalArgumentException("initialCapacity outside range 0 - " + MAX_CAPACITY +
                ": initialCapacity=" + initialCapacity);
        }

        this.isDirect = isDirect;
        if (isDirect)
        {
            if (initialCapacity > 0)
            {
                buffer.wrap(newDirectBuffer(initialCapacity));
            }
            headerBuffer.wrap(newDirectBuffer(HEADER_LENGTH));
        }
        else
        {
            if (initialCapacity > 0)
            {
                buffer.wrap(new byte[initialCapacity]);
            }

View on GitHub (pinned to 6d60124e15)