{"record":{"id":"6e59c733963c7a5d","repo":"aeron-io/aeron","slug":"invalid-block-length-remaining-space-in-term-is","errorCode":null,"errorMessage":"invalid block length , remaining space in term is ","messagePattern":"invalid block length , remaining space in term is ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ExclusivePublication.java","lineNumber":546,"sourceCode":"\n            final int tailCounterOffset = TERM_TAIL_COUNTERS_OFFSET + (activePartitionIndex * SIZE_OF_LONG);\n            final UnsafeBuffer termBuffer = termBuffers[activePartitionIndex];\n            final int result = appendBlock(termBuffer, tailCounterOffset, buffer, offset, length);\n\n            return newPosition(result);\n        }\n        else\n        {\n            return backPressureStatus(position, length);\n        }\n    }\n\n    private void checkBlockLength(final int length)\n    {\n        final int remaining = termBufferLength - termOffset;\n        if (length > remaining)\n        {\n            throw new IllegalArgumentException(\n                \"invalid block length \" + length + \", remaining space in term is \" + remaining);\n        }\n    }\n\n    private void checkFirstFrame(final MutableDirectBuffer buffer, final int offset)\n    {\n        final int frameType = HDR_TYPE_DATA;\n        final int blockTermOffset = buffer.getInt(offset + TERM_OFFSET_FIELD_OFFSET, LITTLE_ENDIAN);\n        final int blockSessionId = buffer.getInt(offset + SESSION_ID_FIELD_OFFSET, LITTLE_ENDIAN);\n        final int blockStreamId = buffer.getInt(offset + STREAM_ID_FIELD_OFFSET, LITTLE_ENDIAN);\n        final int blockTermId = buffer.getInt(offset + TERM_ID_FIELD_OFFSET, LITTLE_ENDIAN);\n        final int blockFrameType = buffer.getShort(offset + TYPE_FIELD_OFFSET, LITTLE_ENDIAN) & 0xFFFF;\n\n        if (blockTermOffset != termOffset ||\n            blockSessionId != sessionId ||\n            blockStreamId != streamId ||\n            blockTermId != termId ||\n            frameType != blockFrameType)","sourceCodeStart":528,"sourceCodeEnd":564,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ExclusivePublication.java#L528-L564","documentation":"ExclusivePublication's internal checkBlockLength() throws this IllegalArgumentException when a block write (e.g. tryAppendBlock or similar API) requests more bytes than remain in the current term at termOffset. A block must fit entirely within the term buffer, otherwise frames would straddle the term boundary, which the protocol forbids.","triggerScenarios":"Appending a block whose length exceeds termBufferLength - termOffset, i.e. near the end of a term with an oversized block, or passing a length larger than the whole term buffer.","commonSituations":"Writing large batches/blocks near term rollover; hard-coded block sizes that exceed a configured term length; switching channels to smaller term lengths without resizing block writes.","solutions":["Cap the block length to the remaining space in the term before appending (query termBufferLength and termOffset).","Retry the append after the term rotates (when termOffset resets).","Increase the channel term-length so the block fits within a single term."],"exampleFix":"// before\npublication.tryAppendBlock(buffer, offset, blockLength);\n// after\nint remaining = publication.termBufferLength() - publication.termOffset();\nif (blockLength <= remaining) {\n    publication.tryAppendBlock(buffer, offset, blockLength);\n}","handlingStrategy":"validation","validationCode":"int remaining = publication.termBufferLength() - publication.termOffset();\nif (blockLength > remaining) {\n    // defer write until after term rotation\n}","typeGuard":null,"tryCatchPattern":"try {\n    publication.tryAppendBlock(buffer, offset, blockLength);\n} catch (IllegalArgumentException e) {\n    // shrink block or wait for next term\n}","preventionTips":["Compute remaining term space before every block append.","Keep block sizes well below the smallest configured term length.","Align block-writing logic with term rollover handling."],"tags":["aeron","publication","argument-validation","term-buffer"],"backgroundTag":"value-out-of-range","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"}