{"record":{"id":"2f1182c7eb3a6fc6","repo":"aeron-io/aeron","slug":"term-offset-termoffset-out-of-range-channel-channeluri","errorCode":null,"errorMessage":"term-offset={termOffset} out of range: channel={channelUri}","messagePattern":"term-offset=(.+?) out of range: channel=(.+?)","errorType":"validation","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":135,"sourceCode":"params.initialTermId = parseInt(initialTermIdStr, INITIAL_TERM_ID_PARAM_NAME);\nparams.termId = parseInt(termIdStr, TERM_ID_PARAM_NAME);\nparams.termOffset = parseInt(termOffsetStr, TERM_OFFSET_PARAM_NAME);\n\nif (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\nif (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}","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L117-L153","documentation":"Raised while parsing publication channel URI parameters: when the complete set of initial-term-id, term-id and term-offset params is supplied, the term-offset value is checked against the log buffer limits. This exception fires when the given termOffset is negative or exceeds LogBufferDescriptor.TERM_MAX_LENGTH, because a term offset outside that range cannot address a position within a term log buffer. It rejects the channel configuration before the publication is created.","triggerScenarios":"A channel URI containing term-offset=-1 or term-offset greater than LogBufferDescriptor.TERM_MAX_LENGTH when adding a publication.","commonSituations":"Using -1 as a 'default' sentinel in the URI; misuniting sizes (e.g. passing bytes value larger than 1GB); generated URIs from buggy tooling.","solutions":["Clamp term-offset to the range 0..TERM_MAX_LENGTH before building the URI","Remove the param entirely if the offset is unknown","Compute the offset from a position as position & (termLength - 1)"],"exampleFix":"// before\n\"aeron:udp?endpoint=...:40456|term-offset=2147483648\"\n// after\n\"aeron:udp?endpoint=...:40456|term-offset=1073741823\"","handlingStrategy":"validation","validationCode":"if (termOffset < 0 || termOffset > LogBufferDescriptor.TERM_MAX_LENGTH) throw new IllegalArgumentException(\"term-offset out of range\");","typeGuard":null,"tryCatchPattern":"try { pub = aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { log.error(\"invalid term-offset: {}\", e.getMessage()); }","preventionTips":["Never use -1 as a sentinel in URIs","Clamp computed offsets before embedding them in URIs","Validate size units (k/m/g) when generating URIs"],"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"}