{"record":{"id":"4969e8820cc08e83","repo":"aeron-io/aeron","slug":"invalid-position-position-channeluri","errorCode":null,"errorMessage":"invalid position: <position>","messagePattern":"invalid position: <position>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUri.java","lineNumber":353,"sourceCode":"\n            sb.setLength(sb.length() - 1);\n        }\n\n        return sb.toString();\n    }\n\n    /**\n     * Initialise a channel for restarting a publication at a given position.\n     *\n     * @param position      at which the publication should be started.\n     * @param initialTermId what which the stream would start.\n     * @param termLength    for the stream.\n     */\n    public void initialPosition(final long position, final int initialTermId, final int termLength)\n    {\n        if (position < 0 || 0 != (position & (FRAME_ALIGNMENT - 1)))\n        {\n            throw new IllegalArgumentException(\"invalid position: \" + position);\n        }\n\n        final int bitsToShift = LogBufferDescriptor.positionBitsToShift(termLength);\n        final int termId = LogBufferDescriptor.computeTermIdFromPosition(position, bitsToShift, initialTermId);\n        final int termOffset = (int)(position & (termLength - 1));\n\n        put(INITIAL_TERM_ID_PARAM_NAME, Integer.toString(initialTermId));\n        put(TERM_ID_PARAM_NAME, Integer.toString(termId));\n        put(TERM_OFFSET_PARAM_NAME, Integer.toString(termOffset));\n        put(TERM_LENGTH_PARAM_NAME, Integer.toString(termLength));\n    }\n\n    /**\n     * Parse a {@link CharSequence} which contains an Aeron URI.\n     *\n     * @param uri to be parsed.\n     * @return a new {@link ChannelUri} representing the URI string.\n     */","sourceCodeStart":335,"sourceCodeEnd":371,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUri.java#L335-L371","documentation":"ChannelUri.initialPosition validates that the requested position is non-negative and FRAME_ALIGNMENT-aligned (multiple of 32 bytes) before encoding it into the channel URI as initialPosition. Positions are term-based (termId/termOffset), so an unaligned or negative value would corrupt log buffer arithmetic.","triggerScenarios":"Calling uri.initialPosition(position, initialTermId, termLength) with position < 0 or position not a multiple of FRAME_ALIGNMENT — e.g. a raw byte offset not rounded to frame alignment, or a computed position using wrong term length.","commonSituations":"Reconstructing a publication position from a recording/catalog value without alignment; computing position from termOffset that wasn't frame-aligned; off-by-one in position arithmetic after restart/failover.","solutions":["Round the position down to a FRAME_ALIGNMENT multiple before passing it: position & ~(FRAME_ALIGNMENT - 1).","Derive the position via LogBufferDescriptor.computePosition(termId, termOffset, positionBitsToShift(termLength), initialTermId) so alignment holds.","Check for negative/overflow in the position computation (e.g. bad termId from a corrupted source)."],"exampleFix":"// before\nuri.initialPosition(rawOffset, initialTermId, termLength);\n// after\nlong aligned = rawOffset & ~(FrameDescriptor.FRAME_ALIGNMENT - 1);\nuri.initialPosition(aligned, initialTermId, termLength);","handlingStrategy":"validation","validationCode":"long aligned = position & ~(FrameDescriptor.FRAME_ALIGNMENT - 1);\nif (position < 0 || aligned != position) throw new IllegalArgumentException(\"position must be frame-aligned\");","typeGuard":null,"tryCatchPattern":"try {\n    uri.initialPosition(position, initialTermId, termLength);\n} catch (IllegalArgumentException e) {\n    // fall back to default (start at position 0) or align and retry\n}","preventionTips":["Compute positions via LogBufferDescriptor.computePosition(...) rather than manual arithmetic","Align any raw offsets to FRAME_ALIGNMENT (32 bytes) before use","Validate positions restored from recordings/catalogs before replaying"],"tags":["aeron","channel-uri","alignment","illegal-argument"],"backgroundTag":"invalid-argument-value","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"}