aeron-io/aeron · error · IllegalArgumentException

offset= capacity=

Error message

offset= capacity=

What it means

DirectBufferVector.validate() throws IllegalArgumentException when the vector's offset is negative or points past the end of the underlying buffer's capacity. Aeron validates each vector before it is used in a vectored write (e.g. publish(vectors...)) so that no memory region outside the buffer is ever read. The exception carries the offending offset and the buffer capacity for diagnosis.

Solutions

1. Check the offset computation: ensure 0 <= offset and offset < buffer.capacity() before constructing the vector.
2. If the vector is reused, re-wrap or rebuild it each time the underlying buffer changes so offset/capacity stay consistent.
3. Log offset and buffer.capacity() at construction time to find where the negative/too-large offset originates.

Example fix

// before
DirectBufferVector vector = new DirectBufferVector(headerBuffer, headerOffset, length);
// after
int off = headerOffset & 0x7FFFFFFF; // or fix the arithmetic
if (off >= headerBuffer.capacity()) { off = 0; }
DirectBufferVector vector = new DirectBufferVector(headerBuffer, off, length);

if (vector.buffer() == null || vector.offset() < 0 || vector.offset() >= vector.buffer().capacity()) {
    throw new IllegalArgumentException("vector offset " + vector.offset() + " invalid for capacity " + vector.buffer().capacity());
}

boolean isValidVector(DirectBufferVector v) {
    return v != null && v.buffer() != null && v.offset() >= 0 && v.offset() < v.buffer().capacity();
}

try {
    publication.offer(vectorBuffer, vectorOffset, vectorLength);
} catch (IllegalArgumentException e) {
    log.error("invalid vector offset/capacity", e);
    metrics.vectorValidationFailures.increment();
}

When it happens

Trigger: Calling Publication.tryClaim or a vectored offer/publish API with a DirectBufferVector whose offset is < 0 or >= buffer.capacity(). Typically caused by computing the offset from a stale buffer (buffer re-wrapped or swapped after the vector was built) or a wrong arithmetic offset value.

Common situations: Passing -1 as a sentinel offset; reusing a vector created for a different (larger) buffer; wrapping a buffer with offset arithmetic (wrap(buffer, baseOffset)) then compounding another offset on top; buffer resized/reallocated between vector construction and send.

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

• offset= capacity= length=
• Invalid fragmentCountLimit=" + fragmentCountLimit
• length overflow:
• padding exceeds maxFramedLength of , length=
• invalid block length , remaining space in term is

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/DirectBufferVector.java:148

    {
        this.length = length;
        return this;
    }

    /**
     * Ensure the vector is valid for the buffer.
     *
     * @throws NullPointerException if the buffer is null.
     * @throws IllegalArgumentException if the offset is out of range for the buffer.
     * @throws IllegalArgumentException if the length is out of range for the buffer.
     * @return this for a fluent API.
     */
    public DirectBufferVector validate()
    {
        final int capacity = buffer.capacity();
        if (offset < 0 || offset >= capacity)
        {
            throw new IllegalArgumentException("offset=" + offset + " capacity=" + capacity);
        }

        if (length < 0 || length > (capacity - offset))
        {
            throw new IllegalArgumentException("offset=" + offset + " capacity=" + capacity + " length=" + length);
        }

        return this;
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public String toString()
    {
        return "DirectBufferVector{" +
            "buffer=" + buffer +

View on GitHub (pinned to 6d60124e15)