{"record":{"id":"78d85792044fbfd7","repo":"aeron-io/aeron","slug":"termoffset-termoffset-out-of-range-channel-channeluri","errorCode":null,"errorMessage":"termOffset=<termOffset> out of range: channel=<channelUri>","messagePattern":"termOffset=<termOffset> out of range: channel=<channelUri>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/SubscriptionParams.java","lineNumber":91,"sourceCode":"        count = termOffsetStr != null ? count + 1 : count;\n\n        if (count > 0)\n        {\n            if (count < 3)\n            {\n                throw new IllegalArgumentException(\"params must be used as a complete set: \" +\n                    INITIAL_TERM_ID_PARAM_NAME + \" \" +\n                    TERM_ID_PARAM_NAME + \" \" +\n                    TERM_OFFSET_PARAM_NAME + \" channel=\" + channelUri);\n            }\n\n            params.initialTermId = Integer.parseInt(initialTermIdStr);\n            params.termId = Integer.parseInt(termIdStr);\n            params.termOffset = Integer.parseInt(termOffsetStr);\n\n            if (params.termOffset < 0 || params.termOffset > LogBufferDescriptor.TERM_MAX_LENGTH)\n            {\n                throw new IllegalArgumentException(\n                    TERM_OFFSET_PARAM_NAME + \"=\" + params.termOffset + \" out of range: channel=\" + channelUri);\n            }\n\n            if (!FrameDescriptor.isFrameAligned(params.termOffset))\n            {\n                throw new IllegalArgumentException(\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 IllegalStateException(\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","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/SubscriptionParams.java#L73-L109","documentation":"When an explicit join position is given via URI params, term-offset must be within [0, TERM_MAX_LENGTH] (the configured term buffer length limit). The driver validates the parsed value and rejects offsets outside that range with IllegalArgumentException.","triggerScenarios":"Subscription URI with term-offset negative or greater than LogBufferDescriptor.TERM_MAX_LENGTH (e.g. term-offset=99999999 with 64MB terms).","commonSituations":"Copy-pasting a file position instead of a term offset; assuming offsets are in bytes of the whole log rather than a single term; unit confusion (KB/MB).","solutions":["Set term-offset within 0..TERM_MAX_LENGTH for the driver's term buffer length.","Compute the offset from the desired position: termOffset = (int)(position & (termLength - 1)).","Check the driver's term-buffer-length config and scale term-id accordingly instead of inflating the offset."],"exampleFix":"// before\nuri += \"|term-offset=\" + position; // absolute log position\n// after\nint termOffset = (int)(position & (termLength - 1));\nuri += \"|term-offset=\" + termOffset;","handlingStrategy":"validation","validationCode":"if (termOffset < 0 || termOffset > LogBufferDescriptor.TERM_MAX_LENGTH) {\n    throw new IllegalArgumentException(\"termOffset out of range: \" + termOffset);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive termOffset from position with position & (termLength - 1).","Do not confuse absolute log positions with per-term offsets."],"tags":["aeron","subscription","range-check","config"],"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"}