{"record":{"id":"cae8753e412a0fea","repo":"elastic/elasticsearch","slug":"distances-array-must-have-length-4-but-was","errorCode":null,"errorMessage":"distances array must have length >= 4, but was: {}","messagePattern":"distances array must have length >= 4, but was: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/simdvec/src/main/java/org/elasticsearch/simdvec/ESVectorUtil.java","lineNumber":297,"sourceCode":"\n    /** Returns the sum of squared differences of the two byte vectors over a sub-range. */\n    public static float squareDistance(byte[] a, byte[] b, int offset, int length) {\n        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,","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/simdvec/src/main/java/org/elasticsearch/simdvec/ESVectorUtil.java#L279-L315","documentation":"Thrown by squareDistanceBulk (byte, offset variant) when distances.length < 4: the bulk operation writes four floats (one per candidate) into the output array, so it needs at least four slots beyond the offset. The message reports the actual length so you can see how short it is.","triggerScenarios":"Calling squareDistanceBulk with a float[] distances argument whose length is less than 4. Common when reusing a smaller scratch buffer from a non-bulk code path or allocating dist with the wrong constant.","commonSituations":"Scratch buffer sized for a single result (length 1) and reused for a bulk call; allocation typo (e.g. new float[3]); buffer pool that hands out arrays of varying capacity.","solutions":["Allocate the distances buffer as new float[4] (or larger if you intend to also use distancesOffset).","Centralize scratch-buffer allocation in a factory that guarantees minimum length 4 for bulk scorers.","Assert distances.length >= 4 once when the scorer is constructed, not on every call."],"exampleFix":"// before\nfloat[] dist = new float[3];\nESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, 0, dist);\n\n// after\nfloat[] dist = new float[4];\nESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, 0, dist);","handlingStrategy":"validation","validationCode":"if (distances.length < 4) {\n    throw new IllegalArgumentException(\"squareDistanceBulk needs distances.length >= 4, got \" + 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 distances buffer too small\", e);\n}","preventionTips":["Allocate the bulk scratch as new float[4] (or larger when using distancesOffset).","Centralize bulk scratch allocation so the minimum-4 invariant is enforced once.","Do not share a single-result scratch buffer with the bulk code path."],"tags":["vector","simd","bulk","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"}