aeron-io/aeron · error · IllegalArgumentException

message exceeds maxMessageLength of

Error message

message exceeds maxMessageLength of {maxMessageLength}, length={length}

What it means

Thrown by Publication.checkMaxMessageLength when a length passed to offer exceeds maxMessageLength. maxMessageLength (termBufferLength/2 minus MessageHeader length) is the largest single frame the publication can send; used by the offer(buffer, ...) API family, distinct from the claim path's maxPayloadLength check.

Solutions

Split the payload into multiple offers each <= publication.maxMessageLength().
Increase the channel's term-length parameter (e.g. term-length=1m) so maxMessageLength grows.
Check publication.maxMessageLength() before offering and log/reject oversized messages at the producer boundary.
Ensure MessageHeader encoding length is accounted for when computing usable size.

Example fix

// before
publication.offer(buffer, 0, serializedLength); // exceeds maxMessageLength

// after
if (serializedLength > publication.maxMessageLength())
{
    throw new IllegalArgumentException("message too large: " + serializedLength);
}
publication.offer(buffer, 0, serializedLength);

Defensive patterns

Strategy: validation

Validate before calling

int maxMessage = publication.maxMessageLength();
if (length > maxMessage) { throw new IllegalArgumentException("message too large: " + length + " > " + maxMessage); }

Type guard

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

Try / catch

try
{
    publication.offer(buffer, offset, length);
}
catch (IllegalArgumentException e)
{
    // exceeded maxMessageLength: split the message or increase term-length
}

Prevention

Compare payload sizes against maxMessageLength() before every offer.
Set term-length on the channel to accommodate your largest message type.
Chunk large datasets into multiple messages with sequence numbers.
Account for MessageHeader size when computing usable message space.

When it happens

Trigger: publication.offer(buffer, offset, length) or offer(directBuffer, ...) with length > publication.maxMessageLength() — typically large serialized objects or batched payloads in one call.

Common situations: Default term buffer sizes with oversized domain messages; growth of average message size after schema changes; attempts to send whole files in one offer.

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

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

Appendix: source

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

    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);
        }

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

        final int totalLength = lengthOne + lengthTwo;

View on GitHub (pinned to 6d60124e15)