{"record":{"id":"975f5d9870611639","repo":"aeron-io/aeron","slug":"term-offset-termoffset-term-length-termlength-channel","errorCode":null,"errorMessage":"term-offset={termOffset} > term-length={termLength}: channel={channelUri}","messagePattern":"term-offset=(.+?) > term-length=(.+?): channel=(.+?)","errorType":"validation","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":128,"sourceCode":"        final String termOffsetStr = channelUri.get(TERM_OFFSET_PARAM_NAME);\n        count = termOffsetStr != null ? count + 1 : count;\n\n        if (count > 0)\n        {\n            if (count < 3)\n            {\n                throw new InvalidChannelException(\"params must be used as a complete set: \" +\n                    INITIAL_TERM_ID_PARAM_NAME + \" \" + TERM_ID_PARAM_NAME + \" \" + TERM_OFFSET_PARAM_NAME + \" channel=\" +\n                    channelUri);\n            }\n\n            params.initialTermId = parseInt(initialTermIdStr, INITIAL_TERM_ID_PARAM_NAME);\n            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)","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L110-L146","documentation":"When term-offset is supplied in the channel URI it must not exceed the publication's term-length, since an offset beyond the term buffer is meaningless. Aeron rejects the channel with InvalidChannelException.","triggerScenarios":"A channel URI with term-offset larger than the resolved term-length (e.g. term-offset=2097152 with default 64KB–1MB term length, or a term-length param smaller than the offset).","commonSituations":"Copying URIs between publications configured with different term-lengths; setting a large term-offset while leaving default (small) term-length; typos like term-offset=1M against a 64KB term buffer.","solutions":["Reduce term-offset to be < term-length","Increase the term-length URI param (power of 2, within TERM_MAX_LENGTH) to exceed the offset","Remove the term-offset param to let Aeron manage positions"],"exampleFix":"// before\n\"aeron:udp?endpoint=...:40456|term-length=65536|term-offset=131072\"\n// after\n\"aeron:udp?endpoint=...:40456|term-length=262144|term-offset=131072\"","handlingStrategy":"validation","validationCode":"if (termOffset >= termLength) throw new IllegalArgumentException(\"term-offset must be < term-length\");","typeGuard":null,"tryCatchPattern":"try { pub = aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { log.error(\"invalid term params: {}\", e.getMessage()); }","preventionTips":["Derive term-offset from position & (termLength - 1)","Keep term-length and term-offset configured together","Assert power-of-two term lengths and offsets within them"],"tags":["aeron","uri","validation"],"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"}