{"record":{"id":"893f1eba974235ea","repo":"aeron-io/aeron","slug":"term-offset-not-in-range-0-1g-termoffset","errorCode":null,"errorMessage":"term offset not in range 0-1g: ${termOffset}","messagePattern":"term offset not in range 0-1g: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":838,"sourceCode":"    {\n        return termId;\n    }\n\n    /**\n     * Set the offset within a term at which a publication will start. This when combined with the term id can establish\n     * a starting position.\n     *\n     * @param termOffset within a term at which a publication will start.\n     * @return this for a fluent API.\n     * @see CommonContext#TERM_OFFSET_PARAM_NAME\n     */\n    public ChannelUriStringBuilder termOffset(final Integer termOffset)\n    {\n        if (null != termOffset)\n        {\n            if ((termOffset < 0 || termOffset > TERM_MAX_LENGTH))\n            {\n                throw new IllegalArgumentException(\"term offset not in range 0-1g: \" + termOffset);\n            }\n\n            if (0 != (termOffset & (FRAME_ALIGNMENT - 1)))\n            {\n                throw new IllegalArgumentException(\"term offset not multiple of FRAME_ALIGNMENT: \" + termOffset);\n            }\n        }\n\n        this.termOffset = termOffset;\n        return this;\n    }\n\n    /**\n     * Set the termOffset value to be what is in the {@link ChannelUri} which may be null.\n     *\n     * @param channelUri to read the value from.\n     * @return this for a fluent API.\n     * @see CommonContext#TERM_OFFSET_PARAM_NAME","sourceCodeStart":820,"sourceCodeEnd":856,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L820-L856","documentation":"ChannelUriStringBuilder.termOffset(Integer) rejects offsets outside the valid range 0..TERM_MAX_LENGTH (0 to 1GB). A term offset is a position inside a term buffer, so negative values or values beyond the term length are meaningless. The error is thrown before the value is stored on the builder.","triggerScenarios":"Calling termOffset() with a negative Integer or one greater than 1073741824, or a URI with 'term-offset=-100' / 'term-offset=2000000000'.","commonSituations":"Computing an offset from a position without masking it into the term; mixing units (bytes vs. offset); resuming a publication with a stale/wrong offset captured from a different term length.","solutions":["Ensure the offset is in 0..termLength range; mask a raw position: (int)(position & (termLength - 1))","Correct negative values that result from signed arithmetic on positions","Use initialPosition(position, initialTermId, termLength) instead, which computes the offset correctly for you"],"exampleFix":"// before\nbuilder.termOffset(-64); // throws\n// after\nbuilder.termOffset(1024);","handlingStrategy":"validation","validationCode":"if (termOffset != null && (termOffset < 0 || termOffset > (1 << 30))) throw new IllegalArgumentException(\"term offset out of range: \" + termOffset);","typeGuard":null,"tryCatchPattern":"try { builder.termOffset(offset); } catch (IllegalArgumentException e) { /* clamp or recompute offset */ }","preventionTips":["Mask raw positions into the term: (int)(position & (termLength - 1))","Prefer initialPosition(...) over manually setting term-id/term-offset","Never pass offsets derived from unsigned or unmasked arithmetic"],"tags":["aeron","uri-validation","argument-out-of-range"],"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"}