aeron-io/aeron · error · IllegalArgumentException

claim exceeds maxPayloadLength=

Error message

claim exceeds maxPayloadLength=<maxPayloadLength>, length=<length>

What it means

Thrown as an IllegalArgumentException when a clustered service attempts to offer a message via ClientSession.offer(buffer, offset, length, headerBuffer) on a follower, and the claim length exceeds the maximum payload the session header buffer can carry. The max payload is computed as headerBuffer.capacity() - SESSION_HEADER_LENGTH. It indicates the service is trying to write a message larger than the configured session header buffer.

Solutions

1. Increase the session header buffer capacity (ClusteredServiceContainer.Configuration session header length) so maxPayloadLength >= message length
2. Reduce the offered message length, or split it into multiple offers
3. Verify you pass the actual payload length, not buffer.capacity(), to offer()
4. Check that the offer is intended on a follower at all; followers must return MOCKED_OFFER and cannot commit log entries

Example fix

// before
int length = buffer.capacity();
session.offer(buffer, 0, length, headerBuffer);
// after
int length = messageLength; // actual payload
if (length <= headerBuffer.capacity() - SessionHeaderLength) {
    session.offer(buffer, 0, length, headerBuffer);
}

int maxPayload = headerBuffer.capacity() - SESSION_HEADER_LENGTH;
if (length > maxPayload) { throw new IllegalArgumentException("length " + length + " > max " + maxPayload); }
session.offer(buffer, 0, length, headerBuffer);

When it happens

Trigger: Calling ClientSession.offer/claim from a service with length > headerBuffer.capacity() - SESSION_HEADER_LENGTH while the cluster node is a follower (MOCKED_OFFER path); headerBuffer sized too small relative to message size; header buffer capacity not enlarged when message sizes grew.

Common situations: Services writing large application messages after changing io.aeron.cluster.session.header.length or reusing a default-sized header buffer; follower-side offer paths failing while leader path might accept via a different mechanism; snapshot/state-machine code passing a buffer-sized length instead of actual payload length.

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

• claim exceeds maxPayloadLength of , length=
• not found in
• ${eventCode}: ${detail}
• clusterMembers and endpoints differ
• response publication already added

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceAgent.java:721

        vectors[0] = headerVector;

        return publication.offer(vectors, null);
    }

    long tryClaim(
        final long clusterSessionId,
        final Publication publication,
        final int length,
        final BufferClaim bufferClaim)
    {
        checkForValidInvocation();

        if (Cluster.Role.LEADER != role)
        {
            final int maxPayloadLength = headerBuffer.capacity() - SESSION_HEADER_LENGTH;
            if (length > maxPayloadLength)
            {
                throw new IllegalArgumentException(
                    "claim exceeds maxPayloadLength=" + maxPayloadLength + ", length=" + length);
            }

            bufferClaim.wrap(
                messageBuffer, 0, DataHeaderFlyweight.HEADER_LENGTH + SESSION_HEADER_LENGTH + length);
            return ClientSession.MOCKED_OFFER;
        }

        if (null == publication)
        {
            return Publication.NOT_CONNECTED;
        }

        final long offset = publication.tryClaim(SESSION_HEADER_LENGTH + length, bufferClaim);
        if (offset > 0)
        {
            sessionMessageHeaderEncoder
                .clusterSessionId(clusterSessionId)

View on GitHub (pinned to 6d60124e15)