{"record":{"id":"28172ce615b17af1","repo":"elastic/elasticsearch","slug":"vector-dimensions-incompatible","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":91,"sourceCode":"        int dimension,\n        int vectorLengthInBytes\n    ) throws IOException {\n        return SCORERS.newES93BinaryQuantizedVectorScorer(input, dimension, vectorLengthInBytes);\n    }\n\n    public static void bFloat16ToFloat(byte[] bfBytes, int bfOffset, float[] floats, int floatOffset, int floatCount, ByteOrder byteOrder) {\n        IMPL.bFloat16ToFloat(bfBytes, bfOffset, floats, floatOffset, floatCount, byteOrder);\n    }\n\n    public static void floatToBFloat16(float[] floats, int floatOffset, byte[] bfBytes, int bfOffset, int floatCount, ByteOrder byteOrder) {\n        assert floats.length - floatOffset >= floatCount;\n        assert (bfBytes.length - bfOffset) >= floatCount * Short.BYTES;\n        IMPL.floatToBFloat16(floats, floatOffset, bfBytes, bfOffset, floatCount, byteOrder);\n    }\n\n    public static float dotProduct(float[] a, float[] b) {\n        if (a.length != b.length) {\n            throw new IllegalArgumentException(\"vector dimensions incompatible: \" + a.length + \"!= \" + b.length);\n        }\n        return IMPL.dotProduct(a, b);\n    }\n\n    /**\n     * Dot product of the first {@code length} components of {@code a} and {@code b}.\n     */\n    public static float dotProduct(float[] a, float[] b, int length) {\n        if (a.length != b.length) {\n            throw new IllegalArgumentException(\"vector dimensions incompatible: \" + a.length + \"!= \" + b.length);\n        }\n        Objects.checkFromIndexSize(0, length, a.length);\n        return IMPL.dotProduct(a, b, 0, length);\n    }\n\n    /**\n     * Dot product over {@code [offset, offset + length)}.\n     */","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/simdvec/src/main/java/org/elasticsearch/simdvec/ESVectorUtil.java#L73-L109","documentation":"Thrown by ESVectorUtil.dotProduct(float[] a, float[] b) when a.length != b.length. Vectors must have identical dimensionality for a dot product; a length mismatch is a programming/contract error, not a runtime data condition. IllegalArgumentException with both lengths in the message.","triggerScenarios":"Passing two float[] of different lengths to dotProduct; one vector read from a stored field of dims N and the query vector built with dims M != N; a config change to dims that left cached/persisted vectors at the old length.","commonSituations":"Index mapping changed number_of_dims after documents were already indexed; query vector built with a different embedding model producing a different dimensionality than the indexed vectors; off-by-one slicing of a vector array.","solutions":["Verify both vectors have the same length before calling: if (a.length != b.length) reject with a domain-specific error.","Ensure index mapping's dims and the query vector's dims come from the same model/config source.","Reindex when the mapping's number_of_dims changes so stored vectors match the new dimensionality.","Prefer the length-bounded overload dotProduct(a,b,length) when you want to operate on a prefix and can guarantee both arrays are at least that long."],"exampleFix":"// before\nfloat score = ESVectorUtil.dotProduct(queryVec, storedVec);\n\n// after\nif (queryVec.length != storedVec.length) {\n    throw new IllegalArgumentException(\"query dims \" + queryVec.length + \" != stored dims \" + storedVec.length);\n}\nfloat score = ESVectorUtil.dotProduct(queryVec, storedVec);","handlingStrategy":"validation","validationCode":"if (a.length != b.length) {\n    throw new IllegalArgumentException(\"dotProduct: a.length \" + a.length + \" != b.length \" + b.length);\n}\nreturn ESVectorUtil.dotProduct(a, b);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate vector lengths at the scorer entry point with full context.","Keep index mapping dims and query dims from the same model/config.","Reindex when number_of_dims changes."],"tags":["simdvec","vectors","dot-product","validation"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}