{"record":{"id":"ff1c0ce04e1c67ff","repo":"aeron-io/aeron","slug":"improperly-formatted-block","errorCode":null,"errorMessage":"improperly formatted block:","messagePattern":"improperly formatted block:","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ExclusivePublication.java","lineNumber":566,"sourceCode":"        }\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)\n        {\n            throw new IllegalArgumentException(\"improperly formatted block:\" +\n                \" termOffset=\" + blockTermOffset + \" (expected=\" + termOffset + \"),\" +\n                \" sessionId=\" + blockSessionId + \" (expected=\" + sessionId + \"),\" +\n                \" streamId=\" + blockStreamId + \" (expected=\" + streamId + \"),\" +\n                \" termId=\" + blockTermId + \" (expected=\" + termId + \"),\" +\n                \" frameType=\" + blockFrameType + \" (expected=\" + frameType + \")\");\n        }\n    }\n\n    private long newPosition(final int resultingOffset)\n    {\n        if (resultingOffset > 0)\n        {\n            termOffset = resultingOffset;\n            return termBeginPosition + resultingOffset;\n        }\n\n        if ((termBeginPosition + termBufferLength) >= maxPossiblePosition)\n        {","sourceCodeStart":548,"sourceCodeEnd":584,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ExclusivePublication.java#L548-L584","documentation":"ExclusivePublication throws this IllegalArgumentException when a block's header fields read back from the buffer do not match the publication's own termOffset, sessionId, streamId, termId, or frame type. This means the block buffer supplied is not the correctly framed block the publication expects at its current position — an internal invariant/contract violation of the block append API.","triggerScenarios":"Calling a block-append API with a buffer whose frame header was built for a different session/stream/term/offset, or with a buffer whose frameType does not match (e.g. PADDING vs DATA), or reusing stale buffers from a previous term.","commonSituations":"Manually constructing frame headers for raw block publication with wrong session or term IDs; passing buffers captured from a different image/publication; protocol-level tooling or replay code writing misaligned frames.","solutions":["Rebuild the block's frame header so termOffset, sessionId, streamId, termId, and frameType exactly match the publication's current values.","Regenerate the block from current publication state instead of reusing a cached/stale buffer.","Verify the frame type written into the header matches the expected block frame type (e.g. HDR_TYPE_DATA vs HDR_TYPE_PAD)."],"exampleFix":"// before\nblockHeader.sessionId = oldSessionId; // stale\npublication.tryAppendBlock(blockBuffer, 0, blockLength);\n// after\nblockHeader.termOffset = publication.termOffset();\nblockHeader.sessionId = publication.sessionId();\nblockHeader.streamId = publication.streamId();\nblockHeader.termId = publication.termId();\npublication.tryAppendBlock(blockBuffer, 0, blockLength);","handlingStrategy":"validation","validationCode":"if (blockTermOffset != publication.termOffset() || blockSessionId != publication.sessionId() ||\n    blockStreamId != publication.streamId() || blockTermId != publication.termId()) {\n    throw new IllegalStateException(\"block header stale; rebuild before append\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    publication.tryAppendBlock(blockBuffer, 0, blockLength);\n} catch (IllegalArgumentException e) {\n    // rebuild frame header from current publication state and retry\n}","preventionTips":["Always build frame headers immediately before the append from live publication state.","Never cache or reuse buffers across terms, sessions, or publications.","Keep a single helper that stamps all five header fields atomically."],"tags":["aeron","publication","frame-header","invariant-violation"],"backgroundTag":"internal-invariant-violation","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"}