{"record":{"id":"42b6e2a2e89d4a94","repo":"aeron-io/aeron","slug":"message-exceeds-maxmessagelength-of-maxmessagelength-length","errorCode":null,"errorMessage":"message exceeds maxMessageLength of {maxMessageLength}, length={length}","messagePattern":"message exceeds maxMessageLength of (.+?), length=(.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/Publication.java","lineNumber":711,"sourceCode":"\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);\n        }\n\n        if (lengthTwo < 0)\n        {\n            throw new IllegalArgumentException(\"lengthTwo < 0: \" + lengthTwo);\n        }\n\n        final int totalLength = lengthOne + lengthTwo;","sourceCodeStart":693,"sourceCodeEnd":729,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/Publication.java#L693-L729","documentation":"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.","triggerScenarios":"publication.offer(buffer, offset, length) or offer(directBuffer, ...) with length > publication.maxMessageLength() — typically large serialized objects or batched payloads in one call.","commonSituations":"Default term buffer sizes with oversized domain messages; growth of average message size after schema changes; attempts to send whole files in one offer.","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."],"exampleFix":"// before\npublication.offer(buffer, 0, serializedLength); // exceeds maxMessageLength\n\n// after\nif (serializedLength > publication.maxMessageLength())\n{\n    throw new IllegalArgumentException(\"message too large: \" + serializedLength);\n}\npublication.offer(buffer, 0, serializedLength);","handlingStrategy":"validation","validationCode":"int maxMessage = publication.maxMessageLength();\nif (length > maxMessage) { throw new IllegalArgumentException(\"message too large: \" + length + \" > \" + maxMessage); }","typeGuard":"boolean fitsInSingleMessage(Publication p, int length) { return length >= 0 && length <= p.maxMessageLength(); }","tryCatchPattern":"try\n{\n    publication.offer(buffer, offset, length);\n}\ncatch (IllegalArgumentException e)\n{\n    // exceeded maxMessageLength: split the message or increase term-length\n}","preventionTips":["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."],"tags":["aeron","publication","message-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"}