{"record":{"id":"3d4811ccd572b86e","repo":"aeron-io/aeron","slug":"term-offset-termoffset-must-be-a-multiple-of-frame-alignment","errorCode":null,"errorMessage":"term-offset={termOffset} must be a multiple of FRAME_ALIGNMENT: channel={channelUri}","messagePattern":"term-offset=(.+?) must be a multiple of FRAME_ALIGNMENT: channel=(.+?)","errorType":"validation","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":141,"sourceCode":"            params.termId = parseInt(termIdStr, TERM_ID_PARAM_NAME);\n            params.termOffset = parseInt(termOffsetStr, TERM_OFFSET_PARAM_NAME);\n\n            if (params.termOffset > params.termLength)\n            {\n                throw new InvalidChannelException(\n                    TERM_OFFSET_PARAM_NAME + \"=\" + params.termOffset + \" > \" +\n                    TERM_LENGTH_PARAM_NAME + \"=\" + params.termLength + \": channel=\" + channelUri);\n            }\n\n            if (params.termOffset < 0 || params.termOffset > LogBufferDescriptor.TERM_MAX_LENGTH)\n            {\n                throw new InvalidChannelException(\n                    TERM_OFFSET_PARAM_NAME + \"=\" + params.termOffset + \" out of range: channel=\" + channelUri);\n            }\n\n            if (!FrameDescriptor.isFrameAligned(params.termOffset))\n            {\n                throw new InvalidChannelException(\n                    TERM_OFFSET_PARAM_NAME + \"=\" + params.termOffset +\n                    \" must be a multiple of FRAME_ALIGNMENT: channel=\" + channelUri);\n            }\n\n            if (params.termId - params.initialTermId < 0)\n            {\n                throw new InvalidChannelException(\n                    \"difference greater than 2^31 - 1: \" + INITIAL_TERM_ID_PARAM_NAME + \"=\" +\n                    params.initialTermId + \" when \" + TERM_ID_PARAM_NAME + \"=\" + params.termId + \" channel=\" +\n                    channelUri);\n            }\n\n            params.hasPosition = true;\n        }\n        else\n        {\n            params.initialTermId = BitUtil.generateRandomisedId();\n            params.termId = params.initialTermId;","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L123-L159","documentation":"Term offsets mark the start of protocol frames, so the term-offset URI parameter must be a multiple of FRAME_ALIGNMENT (32 bytes). Unaligned offsets would corrupt the log buffer framing and are rejected.","triggerScenarios":"A channel URI with a term-offset that is not a multiple of 32 (e.g. term-offset=100) when Aeron.addPublication resolves publication params.","commonSituations":"Deriving offsets by manual arithmetic without aligning; carrying over raw byte positions from a dump; typos in a hand-built URI.","solutions":["Round the offset down/up to a multiple of 32 using BitUtil.align or FrameDescriptor.isFrameAligned","Remove the term-offset param if exact positioning is not required","Compute the offset from a position as position & (termLength - 1), which is frame-aligned for aligned term lengths"],"exampleFix":"// before\n\"aeron:udp?endpoint=...:40456|term-offset=100\"\n// after\n\"aeron:udp?endpoint=...:40456|term-offset=128\"","handlingStrategy":"validation","validationCode":"if (termOffset % FrameAlignment.FRAME_ALIGNMENT != 0) throw new IllegalArgumentException(\"term-offset must be frame-aligned\");","typeGuard":null,"tryCatchPattern":"try { pub = aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { log.error(\"unaligned term-offset: {}\", e.getMessage()); }","preventionTips":["Use BitUtil.align(offset, FRAME_ALIGNMENT) before building URIs","Derive offsets from positions rather than raw byte counts","Add an isFrameAligned assertion in URI-building helpers"],"tags":["aeron","uri","validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}