aeron-io/aeron · error · IllegalArgumentException

padding exceeds maxFramedLength of , length=

Error message

padding exceeds maxFramedLength of , length=

What it means

ExclusivePublication.appendPadding() throws this IllegalArgumentException when the requested padding length is greater than maxFramedLength(). Padding can only be written as a single framed message within a term, so lengths above the maximum framed size cannot be represented. Aeron throws eagerly to prevent writing an invalid frame.

Solutions

1. Clamp the requested padding to publication.maxFramedLength() before calling appendPadding.
2. Increase the channel's term-length (e.g. aeron.term.length=1m) so maxFramedLength covers the desired padding.
3. Split oversized padding across multiple appendPadding/offer calls or use a zero-filled message offer instead.

Example fix

// before
publication.appendPadding(paddingLength);
// after
if (paddingLength > publication.maxFramedLength()) {
    paddingLength = publication.maxFramedLength();
}
publication.appendPadding(paddingLength);

if (paddingLength < 0 || paddingLength > publication.maxFramedLength()) {
    throw new IllegalArgumentException("paddingLength must be <= " + publication.maxFramedLength());
}

try {
    publication.appendPadding(len);
} catch (IllegalArgumentException e) {
    // fall back to publication.offer(zeroFilledBuffer) or split padding
}

When it happens

Trigger: Calling ExclusivePublication.appendPadding(length) with length > publication.maxFramedLength() (which is termLength/2 minus header overhead). E.g. appendPadding on a publication with a small term length but a large padding request.

Common situations: Configuring a term buffer too small (e.g. default 64KB) while padding to align to large boundaries; computing padding size from a user-supplied or network-derived value without clamping; copying code tuned for larger term lengths to a channel with a different term-length setting.

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

• invalid block length , remaining space in term is
• invalid length:
• lengthOne < 0
• lengthTwo < 0
• Invalid fragmentCountLimit=" + fragmentCountLimit

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ExclusivePublication.java:466

            }
        }

        return newPosition;
    }

    /**
     * Append a padding record to log of a given length to make up the log to a position.
     *
     * @param length of the range to claim, in bytes.
     * @return The new stream position, otherwise a negative error value of {@link #NOT_CONNECTED},
     * {@link #BACK_PRESSURED}, {@link #ADMIN_ACTION}, {@link #CLOSED}, or {@link #MAX_POSITION_EXCEEDED}.
     * @throws IllegalArgumentException if the length is greater than {@link #maxMessageLength() framed}.
     */
    public long appendPadding(final int length)
    {
        if (length > maxFramedLength)
        {
            throw new IllegalArgumentException(
                "padding exceeds maxFramedLength of " + maxFramedLength + ", length=" + length);
        }

        long newPosition = CLOSED;
        if (!isClosed)
        {
            final long limit = positionLimit.getVolatile();
            final long position = termBeginPosition + termOffset;

            if (position < limit)
            {
                checkPositiveLength(length);
                final int tailCounterOffset = TERM_TAIL_COUNTERS_OFFSET + (activePartitionIndex * SIZE_OF_LONG);
                final UnsafeBuffer termBuffer = termBuffers[activePartitionIndex];
                final int result = appendPadding(termBuffer, tailCounterOffset, length);

                newPosition = newPosition(result);
            }

View on GitHub (pinned to 6d60124e15)