aeron-io/aeron · error · IllegalArgumentException

limit outside range: capacity=

Error message

limit outside range: capacity=<capacity> limit=<limit>

What it means

BufferBuilder.limit(int) requires 0 <= limit < buffer.capacity(); the current limit must always be a valid position within the allocated buffer. The message reports the buffer's current capacity and the rejected limit value.

Solutions

1. Set limit only to values in [0, capacity-1]; query buffer capacity if exposed, or use reset()/resize-appropriate APIs rather than raw limits.
2. Re-read the current limit/capacity after any operation that may resize the builder instead of caching values.
3. Fix off-by-one: remember limit is an exclusive end position, so max valid value is capacity - 1.

Example fix

// before
builder.limit(builder.capacity()); // off-by-one / stale
// after
int cap = builder.capacity();
if (desiredLimit >= 0 && desiredLimit < cap) {
    builder.limit(desiredLimit);
}

if (newLimit >= 0 && newLimit < builder.capacity()) builder.limit(newLimit);

try {
    builder.limit(desired);
} catch (IllegalArgumentException e) {
    // stale/oversized limit after resize; recompute from current state
}

When it happens

Trigger: Calling builder.limit(n) with n < 0 or n >= buffer.capacity() (capacity changes as the builder resizes, so a previously valid limit can become invalid).

Common situations: Caching an old limit value across a resize/reset; setting limit to buffer capacity off-by-one (limit is exclusive); setting limit before the buffer has grown to the desired size.

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

• initialCapacity outside range 0
• 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/83b06b8e44ff2dac. Report an issue: GitHub.

Appendix: source

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

     * The current limit of the buffer that has been used by append operations.
     *
     * @return the current limit of the buffer that has been used by append operations.
     */
    public int limit()
    {
        return limit;
    }

    /**
     * Set this limit for this buffer as the position at which the next append operation will occur.
     *
     * @param limit to be the new value.
     */
    public void limit(final int limit)
    {
        if (limit < 0 || limit >= buffer.capacity())
        {
            throw new IllegalArgumentException(
                "limit outside range: capacity=" + buffer.capacity() + " limit=" + limit);
        }

        this.limit = limit;
    }

    /**
     * Get the value which the next term offset for a fragment to be assembled should begin at.
     *
     * @return the value which the next term offset for a fragment to be assembled should begin at.
     */
    public int nextTermOffset()
    {
        return nextTermOffset;
    }

    /**
     * Set the value which the next term offset for a fragment to be assembled should begin at.

View on GitHub (pinned to 6d60124e15)