aeron-io/aeron · error · IllegalArgumentException

overflow totalLength=

Error message

overflow totalLength={totalLength}

What it means

Thrown by Publication.validateAndComputeLength when the sum of the two vectored lengths overflows int (totalLength < 0). Both component lengths were individually non-negative but their sum exceeds Integer.MAX_VALUE; Aeron computes the total as an int to size the resulting frame.

Solutions

1. Compute the total as a long and check it against Integer.MAX_VALUE (and maxMessageLength) before the offer.
2. Fix length computations to use remaining() rather than capacity(), avoiding inflated totals.
3. Split very large vectored sends into multiple offers within maxMessageLength().

Example fix

// before
publication.offer(buf1, 0, len1, buf2, 0, len2); // len1 + len2 overflows int

// after
long total = (long) len1 + len2;
if (total < 0 || total > Integer.MAX_VALUE)
{
    throw new IllegalArgumentException("vectored total too large: " + total);
}
publication.offer(buf1, 0, len1, buf2, 0, len2);

long total = (long) lengthOne + lengthTwo;
if (total < 0 || total > publication.maxMessageLength()) { throw new IllegalArgumentException("vectored total too large: " + total); }

boolean fitsVectoredTotal(Publication p, int lengthOne, int lengthTwo) { return ((long) lengthOne + lengthTwo) >= 0 && ((long) lengthOne + lengthTwo) <= p.maxMessageLength(); }

try
{
    publication.offer(buf1, off1, len1, buf2, off2, len2);
}
catch (IllegalArgumentException e)
{
    // int overflow or oversized total: split the send into multiple offers
    log.error("vectored offer too large", e);
}

When it happens

Trigger: publication.offer(...) with two buffers whose combined length exceeds 2^31 - 1 — only reachable with near-2GB buffers, but possible with miscomputed lengths (e.g. accidentally adding capacity instead of remaining()).

Common situations: Very large batched sends combining header and near-Integer.MAX_VALUE payloads; accidental use of buffer.capacity() rather than remaining() when computing lengths; test code constructing extreme sizes.

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

• lengthOne < 0
• lengthTwo < 0
• 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/93ca74ad2a93cbaf. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/Publication.java:732

        }
    }

    static int validateAndComputeLength(final int lengthOne, final int lengthTwo)
    {
        if (lengthOne < 0)
        {
            throw new IllegalArgumentException("lengthOne < 0: " + lengthOne);
        }

        if (lengthTwo < 0)
        {
            throw new IllegalArgumentException("lengthTwo < 0: " + lengthTwo);
        }

        final int totalLength = lengthOne + lengthTwo;
        if (totalLength < 0)
        {
            throw new IllegalArgumentException("overflow totalLength=" + totalLength);
        }

        return totalLength;
    }

    /**
     * Returns a string representation of a position. Generally used for errors. If the position is a valid error then
     * String name of the error will be returned. If the value is 0 or greater the text will be "NONE". If the position
     * is negative, but not a known error code then "UNKNOWN" will be returned.
     *
     * @param position position value returned from a call to offer.
     * @return String representation of the error.
     */
    public static String errorString(final long position)
    {
        if (MAX_POSITION_EXCEEDED <= position && position < 0)
        {
            final int errorCode = (int)position;

View on GitHub (pinned to 6d60124e15)