{"record":{"id":"990b1ae8fb94102d","repo":"aeron-io/aeron","slug":"position-out-of-range","errorCode":null,"errorMessage":" position out of range: -","messagePattern":" position out of range: -","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/Image.java","lineNumber":783,"sourceCode":"     * @param reason a String indicating the reason why this image is being rejected.\n     */\n    public void reject(final String reason)\n    {\n        subscription.rejectImage(correlationId, position(), reason);\n    }\n\n    private UnsafeBuffer activeTermBuffer(final long position)\n    {\n        return termBuffers[LogBufferDescriptor.indexByPosition(position, positionBitsToShift)];\n    }\n\n    private void validatePosition(final long position)\n    {\n        final long currentPosition = subscriberPosition.get();\n        final long limitPosition = (currentPosition - (currentPosition & termLengthMask)) + termLengthMask + 1;\n        if (position < currentPosition || position > limitPosition)\n        {\n            throw new IllegalArgumentException(\n                position + \" position out of range: \" + currentPosition + \"-\" + limitPosition);\n        }\n\n        if (0 != (position & (FRAME_ALIGNMENT - 1)))\n        {\n            throw new IllegalArgumentException(position + \" position not aligned to FRAME_ALIGNMENT\");\n        }\n    }\n\n    LogBuffers logBuffers()\n    {\n        return logBuffers;\n    }\n\n    void close()\n    {\n        finalPosition = subscriberPosition.getVolatile();\n        eosPosition = LogBufferDescriptor.endOfStreamPosition(logBuffers.metaDataBuffer());","sourceCodeStart":765,"sourceCodeEnd":801,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/Image.java#L765-L801","documentation":"Image.validatePosition() throws this IllegalArgumentException when a caller-supplied position is below the subscriber's current position or beyond the limit of the current term (currentTermStartOffset + termLength). Positions passed to controlled/subscriber advance APIs must fall within the readable window.","triggerScenarios":"Calling Image position-setting methods (e.g. position(long)) with a position < currentPosition or > term-window limit; saving/restoring positions computed against a different term; miscomputed offsets after term rollover.","commonSituations":"Subscribers persisting and restoring positions across restarts with stale term metadata; manually advancing a subscription position past the term boundary; clock/ordering bugs where an older recorded position is replayed.","solutions":["Clamp the requested position to [image.position(), currentTermStartPosition + termLength] before setting.","Align the position to a valid frame boundary and to the current term's range; recompute from image.position() when in doubt.","Persist enough metadata (termId + position) so restored positions remain within the image's window."],"exampleFix":"// before\nimage.position(savedPosition);\n// after\nlong min = image.position();\nlong max = (min - (min & (termLength - 1))) + termLength;\nif (savedPosition >= min && savedPosition <= max) {\n    image.position(savedPosition);\n}","handlingStrategy":"validation","validationCode":"long current = image.position();\nlong limit = (current - (current & (image.termLength() - 1))) + image.termLength();\nif (targetPosition < current || targetPosition > limit) {\n    throw new IllegalArgumentException(\"position out of range: \" + current + \"-\" + limit);\n}","typeGuard":null,"tryCatchPattern":"try {\n    image.position(savedPosition);\n} catch (IllegalArgumentException e) {\n    // clamp to image.position() and log the stale position\n}","preventionTips":["Persist termId together with position and validate it on restore.","Only set positions previously obtained from image.position().","Recompute limits at call time; never cache them across term boundaries."],"tags":["aeron","image","subscriber","position-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-16T04:17:20.429Z"}