{"record":{"id":"0c44411a84e41f86","repo":"elastic/elasticsearch","slug":"distancesoffset-must-be-between-have-length-0-and","errorCode":null,"errorMessage":"distancesOffset must be between have length 0 and distances.length - 4","messagePattern":"distancesOffset must be between have length 0 and distances\\.length - 4","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/simdvec/src/main/java/org/elasticsearch/simdvec/ESVectorUtil.java","lineNumber":720,"sourceCode":"     * @throws IllegalArgumentException if the dimensions of the vectors do not match or if the distances array does not have length 4\n     */\n    public static void squareDistanceBulk(\n        float[] q,\n        float[] v0,\n        float[] v1,\n        float[] v2,\n        float[] v3,\n        int distancesOffset,\n        float[] distances\n    ) {\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 have length 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 between a query vector and four vectors.Result is stored in the provided distances array.\n     *\n     * @param q the query vector\n     * @param v0 the first vector\n     * @param v1 the second vector\n     * @param v2 the third vector\n     * @param v3 the fourth vector\n     * @param distancesOffset offset to the location in the distances array where we want to store the 4 results,\n     *                        we require distancesOffset to be between 0 and distances.length - 4\n     * @param distances an array to store the computed square distances, must have length >= 4\n     *\n     * @throws IllegalArgumentException if the dimensions of the vectors do not match or if the distances array does not have length 4\n     */","sourceCodeStart":702,"sourceCodeEnd":738,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/simdvec/src/main/java/org/elasticsearch/simdvec/ESVectorUtil.java#L702-L738","documentation":"Thrown by ESVectorUtil.squareDistanceBulk (distancesOffset overload) when distancesOffset is negative or larger than distances.length - 4. The method writes four consecutive results starting at distancesOffset, so the offset must leave room for all four. Note: the message text contains a known typo ('between have length 0').","triggerScenarios":"Calling squareDistanceBulk with distancesOffset < 0, or distancesOffset > distances.length - 4. For example, offset 2 into a length-4 array triggers it because 2 > 4 - 4 = 0.","commonSituations":"A caller packs multiple bulk results into one large distances array and computes the offset incorrectly (off-by-one, or not accounting for the fixed 4-result stride). Also occurs when distancesOffset is derived from a node ordinal without clamping.","solutions":["Ensure 0 <= distancesOffset and distancesOffset + 4 <= distances.length before calling.","If packing results, advance the offset by exactly 4 per batch and stop before the end of the buffer.","If only one batch is needed, pass distancesOffset = 0 and a length-4 array."],"exampleFix":"// before\nESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, offset, dists);\n\n// after\nif (offset < 0 || offset + 4 > dists.length) {\n    throw new IllegalArgumentException(\"bad offset \" + offset + \" for dists len \" + dists.length);\n}\nESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, offset, dists);","handlingStrategy":"validation","validationCode":"if (distancesOffset < 0 || distancesOffset > distances.length - 4) {\n    throw new IllegalArgumentException(\"offset \" + distancesOffset + \" out of range for len \" + distances.length);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Advance offsets by exactly 4 when packing batches.","Assert offset + 4 <= distances.length in debug builds.","Use offset 0 for single-batch calls to avoid arithmetic errors."],"tags":["vector-search","knn","offset-bounds","simd","elasticsearch"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}