{"record":{"id":"725289fc4c64ee50","repo":"elastic/elasticsearch","slug":"distancesoffset-must-be-between-0-and-distances-le","errorCode":null,"errorMessage":"distancesOffset must be between 0 and distances.length - 4","messagePattern":"distancesOffset must be between 0 and distances\\.length - 4","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/simdvec/src/main/java/org/elasticsearch/simdvec/ESVectorUtil.java","lineNumber":300,"sourceCode":"        if (a.length != b.length) {\n            throw new IllegalArgumentException(\"vector dimensions incompatible: \" + a.length + \"!= \" + b.length);\n        }\n        Objects.checkFromIndexSize(offset, length, a.length);\n        return IMPL.squareDistance(a, b, offset, length);\n    }\n\n    /**\n     * Bulk computation of square distances from a byte query vector to four byte candidate vectors.\n     */\n    public static void squareDistanceBulk(byte[] q, byte[] v0, byte[] v1, byte[] v2, byte[] v3, int distancesOffset, float[] distances) {\n        if (q.length != v0.length || q.length != v1.length || q.length != v2.length || q.length != v3.length) {\n            throw new IllegalArgumentException(\"vector dimensions incompatible\");\n        }\n        if (distances.length < 4) {\n            throw new IllegalArgumentException(\"distances array must have length >= 4, but was: \" + distances.length);\n        }\n        if (distancesOffset < 0 || distancesOffset > distances.length - 4) {\n            throw new IllegalArgumentException(\"distancesOffset must be between 0 and distances.length - 4\");\n        }\n        IMPL.squareDistanceBulk(q, 0, v0, v1, v2, v3, distancesOffset, distances, q.length);\n    }\n\n    /**\n     * Bulk computation of square distances from a sub-range of a byte query vector to four byte candidate vectors.\n     */\n    public static void squareDistanceBulk(\n        byte[] q,\n        int qOffset,\n        int length,\n        byte[] v0,\n        byte[] v1,\n        byte[] v2,\n        byte[] v3,\n        float[] distances\n    ) {\n        if (q.length != v0.length || q.length != v1.length || q.length != v2.length || q.length != v3.length) {","sourceCodeStart":282,"sourceCodeEnd":318,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/simdvec/src/main/java/org/elasticsearch/simdvec/ESVectorUtil.java#L282-L318","documentation":"Thrown by squareDistanceBulk (byte, offset variant) when distancesOffset is out of range: the method writes four consecutive floats starting at distancesOffset, so the offset must satisfy 0 <= distancesOffset <= distances.length - 4. Negative offsets and offsets too close to the end are both rejected. The message names the valid range.","triggerScenarios":"Passing a negative distancesOffset, or a positive offset that leaves fewer than 4 slots before the end of the distances array. Typical when a shared scratch array is advanced past its usable window during batched scoring.","commonSituations":"Batching multiple bulk calls into one scratch array and forgetting to leave 4 slots of headroom; cursor that increments by the wrong stride; underflow when distances.length is exactly 4 and offset is nonzero.","solutions":["Clamp distancesOffset to [0, distances.length - 4] before each call.","When the scratch cursor reaches the limit, flush and reset to 0 instead of advancing.","Size the scratch array as a multiple of 4 plus headroom so stride math stays in range."],"exampleFix":"// before\nint off = cursor; // could exceed distances.length - 4\nESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, off, dist);\n\n// after\nint maxOff = dist.length - 4;\nif (cursor < 0 || cursor > maxOff) cursor = 0; // flush+reset policy\nESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, cursor, dist);","handlingStrategy":"validation","validationCode":"if (distancesOffset < 0 || distancesOffset > distances.length - 4) {\n    throw new IllegalArgumentException(\"squareDistanceBulk distancesOffset out of range: \" + distancesOffset\n        + \" for distances.length \" + distances.length);\n}\nESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, distancesOffset, distances);","typeGuard":null,"tryCatchPattern":"try {\n    ESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, off, dist);\n} catch (IllegalArgumentException e) {\n    throw new QueryException(\"squareDistanceBulk bad offset\", e);\n}","preventionTips":["Clamp distancesOffset to [0, distances.length - 4] before each call.","When the scratch cursor would overflow, flush and reset to 0 instead of advancing.","Size scratch as a whole multiple of 4 so stride math stays in range."],"tags":["vector","simd","bulk","offset","scratch-buffer","square-distance","elasticsearch"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}