{"record":{"id":"16ca7117ebf5cefd","repo":"elastic/elasticsearch","slug":"vector-dimensions-incompatible-16ca71","errorCode":null,"errorMessage":"vector dimensions incompatible","messagePattern":"vector dimensions incompatible","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/simdvec/src/main/java/org/elasticsearch/simdvec/ESVectorUtil.java","lineNumber":294,"sourceCode":"        }\n        return IMPL.squareDistance(a, b);\n    }\n\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,","sourceCodeStart":276,"sourceCodeEnd":312,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/simdvec/src/main/java/org/elasticsearch/simdvec/ESVectorUtil.java#L276-L312","documentation":"Thrown by squareDistanceBulk(byte[] q, byte[] v0, v1, v2, v3, int distancesOffset, float[] distances): bulk squared distance from one byte query to four byte candidates. The guard rejects when q.length differs from any of v0..v3.length. Note the message is plain 'vector dimensions incompatible' (no sizes embedded) — inspect lengths yourself to localize the offending candidate.","triggerScenarios":"Calling squareDistanceBulk where one of the four candidate byte vectors (v0..v3) has a different length from the query. Typical during HNSW graph traversal when a neighbor vector was decoded with a stale/shorter buffer, or when fewer than four real candidates are padded with differently-sized placeholders.","commonSituations":"Graph traversal padding short candidate slots with zero-length or differently-sized buffers; mixed quantization tiers across segments; a candidate loaded from a corrupted/shorter BytesRef; cross-version segment with different quantized dims.","solutions":["Before calling, assert q.length == v0.length == v1.length == v2.length == v3.length and log which one diverges.","When padding candidate slots in graph traversal, pad with copies of a correctly-sized zero vector, not empty arrays.","Validate decoded candidate length against the segment's quantized dims at read time."],"exampleFix":"// before\nESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, off, dist); // v2 wrong size\n\n// after\nfor (byte[] v : new byte[][]{v0, v1, v2, v3}) {\n    if (v.length != q.length) throw new IllegalArgumentException(\n        \"candidate length \" + v.length + \" != query \" + q.length);\n}\nESVectorUtil.squareDistanceBulk(q, v0, v1, v2, v3, off, dist);","handlingStrategy":"validation","validationCode":"int n = q.length;\nif (v0.length!=n || v1.length!=n || v2.length!=n || v3.length!=n) {\n    throw new IllegalArgumentException(\"squareDistanceBulk candidate/query length mismatch: q=\" + n\n        + \" v0=\" + v0.length + \" v1=\" + v1.length + \" v2=\" + v2.length + \" v3=\" + v3.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 args (dims or scratch)\", e);\n}","preventionTips":["Pad graph-traversal candidate slots with correctly-sized zero vectors, not empty arrays.","Validate decoded candidate length against the segment's quantized dims at read time.","Log the divergent candidate index when the precondition fails."],"tags":["vector","simd","bulk","square-distance","dimensions","elasticsearch","knn"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}