{"record":{"id":"5d32cd4f64e4494f","repo":"aeron-io/aeron","slug":"claim-exceeds-maxpayloadlength-of-length","errorCode":null,"errorMessage":"claim exceeds maxPayloadLength of , length=","messagePattern":"claim exceeds maxPayloadLength of , length=","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/Publication.java","lineNumber":703,"sourceCode":"\n    final void checkPositiveLength(final int length)\n    {\n        if (length < 0)\n        {\n            throw new IllegalArgumentException(\"invalid length: \" + length);\n        }\n    }\n\n    final void checkPayloadLength(final int length)\n    {\n        if (length < 0)\n        {\n            throw new IllegalArgumentException(\"invalid length: \" + length);\n        }\n\n        if (length > maxPayloadLength)\n        {\n            throw new IllegalArgumentException(\n                \"claim exceeds maxPayloadLength of \" + maxPayloadLength + \", length=\" + length);\n        }\n    }\n\n    final void checkMaxMessageLength(final int length)\n    {\n        if (length > maxMessageLength)\n        {\n            throw new IllegalArgumentException(\n                \"message exceeds maxMessageLength of \" + maxMessageLength + \", length=\" + length);\n        }\n    }\n\n    static int validateAndComputeLength(final int lengthOne, final int lengthTwo)\n    {\n        if (lengthOne < 0)\n        {\n            throw new IllegalArgumentException(\"lengthOne < 0: \" + lengthOne);","sourceCodeStart":685,"sourceCodeEnd":721,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/Publication.java#L685-L721","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Chunk the payload into messages <= publication.maxPayloadLength() and reassemble on the consumer.","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).","Query publication.maxPayloadLength() at startup and enforce it in the producer before claiming.","Consider file-log/-extension or an external transfer mechanism for very large blobs."],"exampleFix":"// before\npublication.tryClaim(hugePayloadLength, reservedValue); // IllegalArgumentException\n\n// after\nif (hugePayloadLength > publication.maxPayloadLength())\n{\n    // chunk or configure term-length=1m on the channel\n}\n","handlingStrategy":"validation","validationCode":"int maxPayload = publication.maxPayloadLength();\nif (length > maxPayload) { /* chunk into <= maxPayload pieces or fail */ }","typeGuard":"boolean fitsInClaim(Publication p, int length) { return length >= 0 && length <= p.maxPayloadLength(); }","tryCatchPattern":"try\n{\n    publication.tryClaim(length, reservedValue);\n}\ncatch (IllegalArgumentException e)\n{\n    // length exceeded maxPayloadLength: chunk the payload or enlarge term-length\n}","preventionTips":["Configure an adequate term-length (e.g. 1m) for channels carrying large messages.","Query maxPayloadLength() at startup and enforce it in serialization code.","Chunk large payloads and reassemble on the consumer instead of raising term length indefinitely.","Add a size check test in CI for every message type sent over Aeron."],"tags":["aeron","publication","payload-size","configuration"],"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"}