{"record":{"id":"d2ea5902cf311175","repo":"aeron-io/aeron","slug":"termoffset-termoffset-termlength-termlength","errorCode":null,"errorMessage":"termOffset=${termOffset} > termLength=${termLength}","messagePattern":"termOffset=(.+?) > termLength=(.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":242,"sourceCode":"        final boolean anyNonNull = null != initialTermId || null != termId || null != termOffset;\n        final boolean anyNull = null == initialTermId || null == termId || null == termOffset;\n        if (anyNonNull)\n        {\n            if (anyNull)\n            {\n                throw new IllegalArgumentException(\n                    \"either all or none of the parameters ['initialTermId', 'termId', 'termOffset'] must be provided\");\n            }\n\n            if (termId - initialTermId < 0)\n            {\n                throw new IllegalArgumentException(\n                    \"difference greater than 2^31 - 1: termId=\" + termId + \" - initialTermId=\" + initialTermId);\n            }\n\n            if (null != termLength && termOffset > termLength)\n            {\n                throw new IllegalArgumentException(\"termOffset=\" + termOffset + \" > termLength=\" + termLength);\n            }\n        }\n\n        return this;\n    }\n\n    /**\n     * Set the prefix for taking an additional action such as spying on an outgoing publication with \"aeron-spy\".\n     *\n     * @param prefix to be applied to the URI before the scheme.\n     * @return this for a fluent API.\n     * @see ChannelUri#SPY_QUALIFIER\n     */\n    public ChannelUriStringBuilder prefix(final String prefix)\n    {\n        if (null != prefix && !prefix.isEmpty() && !prefix.equals(SPY_QUALIFIER))\n        {\n            throw new IllegalArgumentException(\"invalid prefix: \" + prefix);","sourceCodeStart":224,"sourceCodeEnd":260,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L224-L260","documentation":"Thrown by ChannelUriStringBuilder.validate() when termOffset is set and exceeds the configured termLength. A term offset must point within the term buffer, so an offset greater than the term length would address outside the buffer and cannot produce a valid channel URI.","triggerScenarios":"Calling validate() with builder.termLength(64*1024).termOffset(100*1024), or deriving termOffset from a position whose low bits exceed the chosen termLength (e.g. termLength smaller than the position's modulo).","commonSituations":"Setting an initialPosition whose offset component exceeds a hand-set termLength; mixing parameters copied from a URI with a different term length (e.g. 64k term length but offset from a 1MB-term recording).","solutions":["Increase termLength (typically to a power of 2 like 1MB, 16MB) so it is >= termOffset.","Reduce termOffset to a value within [0, termLength).","Drop explicit termLength and let the builder/driver pick the default."],"exampleFix":"// before\nbuilder.termLength(1 << 16).termOffset(1 << 20).validate();\n// after\nbuilder.termLength(1 << 24).termOffset(1 << 20).validate();","handlingStrategy":"validation","validationCode":"if (termLength != null && termOffset != null && termOffset > termLength) { throw new IllegalArgumentException(\"termOffset must be <= termLength\"); }","typeGuard":"boolean offsetWithinTerm(Integer termLength, Integer termOffset) { return termLength == null || termOffset == null || termOffset <= termLength; }","tryCatchPattern":"try { uri = builder.validate().build(); } catch (IllegalArgumentException e) { log.warn(\"invalid term params\", e); uri = defaultBuilder.build(); }","preventionTips":["Derive termOffset/termLength from a single position value instead of setting them independently","Use standard term lengths (64k, 1m, 16m)","Compute offset as (int)(position & (termLength - 1))"],"tags":["aeron","channel-uri","validation","configuration"],"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"}