{"record":{"id":"ea6fabf3d1793f47","repo":"aeron-io/aeron","slug":"claim-exceeds-maxpayloadlength-maxpayloadlength-length","errorCode":null,"errorMessage":"claim exceeds maxPayloadLength=<maxPayloadLength>, length=<length>","messagePattern":"claim exceeds maxPayloadLength=<maxPayloadLength>, length=<length>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceAgent.java","lineNumber":721,"sourceCode":"        vectors[0] = headerVector;\n\n        return publication.offer(vectors, null);\n    }\n\n    long tryClaim(\n        final long clusterSessionId,\n        final Publication publication,\n        final int length,\n        final BufferClaim bufferClaim)\n    {\n        checkForValidInvocation();\n\n        if (Cluster.Role.LEADER != role)\n        {\n            final int maxPayloadLength = headerBuffer.capacity() - SESSION_HEADER_LENGTH;\n            if (length > maxPayloadLength)\n            {\n                throw new IllegalArgumentException(\n                    \"claim exceeds maxPayloadLength=\" + maxPayloadLength + \", length=\" + length);\n            }\n\n            bufferClaim.wrap(\n                messageBuffer, 0, DataHeaderFlyweight.HEADER_LENGTH + SESSION_HEADER_LENGTH + length);\n            return ClientSession.MOCKED_OFFER;\n        }\n\n        if (null == publication)\n        {\n            return Publication.NOT_CONNECTED;\n        }\n\n        final long offset = publication.tryClaim(SESSION_HEADER_LENGTH + length, bufferClaim);\n        if (offset > 0)\n        {\n            sessionMessageHeaderEncoder\n                .clusterSessionId(clusterSessionId)","sourceCodeStart":703,"sourceCodeEnd":739,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceAgent.java#L703-L739","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase the session header buffer capacity (ClusteredServiceContainer.Configuration session header length) so maxPayloadLength >= message length","Reduce the offered message length, or split it into multiple offers","Verify you pass the actual payload length, not buffer.capacity(), to offer()","Check that the offer is intended on a follower at all; followers must return MOCKED_OFFER and cannot commit log entries"],"exampleFix":"// before\nint length = buffer.capacity();\nsession.offer(buffer, 0, length, headerBuffer);\n// after\nint length = messageLength; // actual payload\nif (length <= headerBuffer.capacity() - SessionHeaderLength) {\n    session.offer(buffer, 0, length, headerBuffer);\n}","handlingStrategy":"validation","validationCode":"int maxPayload = headerBuffer.capacity() - SESSION_HEADER_LENGTH;\nif (length > maxPayload) { throw new IllegalArgumentException(\"length \" + length + \" > max \" + maxPayload); }\nsession.offer(buffer, 0, length, headerBuffer);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Size the session header buffer for the largest message your service offers","Offer actual payload length, never buffer.capacity()","Remember followers return MOCKED_OFFER; only the leader's offer commits"],"tags":["aeron","cluster","payload-size","follower"],"backgroundTag":"payload-too-large","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}