aeron-io/aeron · error · IllegalArgumentException

claim exceeds maxPayloadLength of , length=

Error message

claim exceeds maxPayloadLength of , length=

What it means

Thrown by Publication.checkPayloadLength when the requested length exceeds the publication's maxPayloadLength. maxPayloadLength equals termBufferLength/2 minus term metadata (via termWindowLength), so messages must fit within a term window. Splitting/reassembly of larger messages is not done for claims; callers must chunk or use a bigger term buffer.

Solutions

1. Chunk the payload into messages <= publication.maxPayloadLength() and reassemble on the consumer.
2. Increase the term length on the channel (e.g. aeron:udp?term-length=1m) or at the channel builder so maxPayloadLength grows (must be power of 2, >= 64KB, <= 1GB).
3. Query publication.maxPayloadLength() at startup and enforce it in the producer before claiming.
4. Consider file-log/-extension or an external transfer mechanism for very large blobs.

Example fix

// before
publication.tryClaim(hugePayloadLength, reservedValue); // IllegalArgumentException

// after
if (hugePayloadLength > publication.maxPayloadLength())
{
    // chunk or configure term-length=1m on the channel
}

int maxPayload = publication.maxPayloadLength();
if (length > maxPayload) { /* chunk into <= maxPayload pieces or fail */ }

boolean fitsInClaim(Publication p, int length) { return length >= 0 && length <= p.maxPayloadLength(); }

try
{
    publication.tryClaim(length, reservedValue);
}
catch (IllegalArgumentException e)
{
    // length exceeded maxPayloadLength: chunk the payload or enlarge term-length
}

When it happens

Trigger: publication.tryClaim(length) with length > maxPayloadLength — e.g. sending multi-MB payloads over a publication configured with the default 64KB term length, or claiming whole-file bodies without chunking.

Common situations: Default term-length configuration (16/64KB) with application messages that grew over time; large file transfer attempts over a single claim; choosing termLength at channel level without revisiting message sizes.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• message exceeds maxMessageLength of
• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• segment file length not a power of 2
• segment file length not in valid range

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

Appendix: source

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

    final void checkPositiveLength(final int length)
    {
        if (length < 0)
        {
            throw new IllegalArgumentException("invalid length: " + length);
        }
    }

    final void checkPayloadLength(final int length)
    {
        if (length < 0)
        {
            throw new IllegalArgumentException("invalid length: " + length);
        }

        if (length > maxPayloadLength)
        {
            throw new IllegalArgumentException(
                "claim exceeds maxPayloadLength of " + maxPayloadLength + ", length=" + length);
        }
    }

    final void checkMaxMessageLength(final int length)
    {
        if (length > maxMessageLength)
        {
            throw new IllegalArgumentException(
                "message exceeds maxMessageLength of " + maxMessageLength + ", length=" + length);
        }
    }

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

View on GitHub (pinned to 6d60124e15)