{"record":{"id":"44c69617f3cf66e2","repo":"spring-projects/spring-ai","slug":"vectors-lengths-must-be-equal","errorCode":null,"errorMessage":"Vectors lengths must be equal","messagePattern":"Vectors lengths must be equal","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/SimpleVectorStore.java","lineNumber":275,"sourceCode":"\n\t\treturn VectorStoreObservationContext.builder(VectorStoreProvider.SIMPLE.value(), operationName)\n\t\t\t.dimensions(this.embeddingModel.dimensions())\n\t\t\t.collectionName(\"in-memory-map\")\n\t\t\t.similarityMetric(VectorStoreSimilarityMetric.COSINE.value());\n\t}\n\n\tpublic static final class EmbeddingMath {\n\n\t\tprivate EmbeddingMath() {\n\t\t\tthrow new UnsupportedOperationException(\"This is a utility class and cannot be instantiated\");\n\t\t}\n\n\t\tpublic static double cosineSimilarity(float[] vectorX, float[] vectorY) {\n\t\t\tif (vectorX == null || vectorY == null) {\n\t\t\t\tthrow new RuntimeException(\"Vectors must not be null\");\n\t\t\t}\n\t\t\tif (vectorX.length != vectorY.length) {\n\t\t\t\tthrow new IllegalArgumentException(\"Vectors lengths must be equal\");\n\t\t\t}\n\n\t\t\tfloat dotProduct = dotProduct(vectorX, vectorY);\n\t\t\tfloat normX = norm(vectorX);\n\t\t\tfloat normY = norm(vectorY);\n\n\t\t\tif (normX == 0 || normY == 0) {\n\t\t\t\tthrow new IllegalArgumentException(\"Vectors cannot have zero norm\");\n\t\t\t}\n\n\t\t\treturn dotProduct / (Math.sqrt(normX) * Math.sqrt(normY));\n\t\t}\n\n\t\tpublic static float dotProduct(float[] vectorX, float[] vectorY) {\n\t\t\tif (vectorX.length != vectorY.length) {\n\t\t\t\tthrow new IllegalArgumentException(\"Vectors lengths must be equal\");\n\t\t\t}\n","sourceCodeStart":257,"sourceCodeEnd":293,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/SimpleVectorStore.java#L257-L293","documentation":"EmbeddingMath.cosineSimilarity throws IllegalArgumentException 'Vectors lengths must be equal' when the two float[] vectors have different dimensions. Cosine similarity is only defined for vectors of the same embedding dimensionality.","triggerScenarios":"Comparing embeddings from two different embedding models (e.g. 384-dim vs 1536-dim), or a corrupted/partially deserialized vector store where stored vectors have a stale dimensionality.","commonSituations":"Switching embedding models without rebuilding the vector store; mixing documents embedded with different models; manual test fixtures with hand-written vectors.","solutions":["Use one embedding model consistently; rebuild/re-embed the store after changing models.","Check vectorX.length == vectorY.length before calling and log/skip mismatches.","Validate dimensionality at ingestion time to catch bad vectors early."],"exampleFix":"// before\ndouble s = EmbeddingMath.cosineSimilarity(newEmbedding, storedVector); // dims may differ\n\n// after\nif (newEmbedding.length == storedVector.length) {\n    double s = EmbeddingMath.cosineSimilarity(newEmbedding, storedVector);\n}\nelse {\n    throw new IllegalStateException(\"Embedding model changed - re-index the store\");\n}","handlingStrategy":"validation","validationCode":"if (vectorX.length != vectorY.length) {\n    throw new IllegalStateException(\"Embedding dimension mismatch: \" + vectorX.length + \" vs \" + vectorY.length);\n}\ndouble s = EmbeddingMath.cosineSimilarity(vectorX, vectorY);","typeGuard":"static boolean sameDimension(float[] a, float[] b) { return a != null && b != null && a.length == b.length; }","tryCatchPattern":"try {\n    return EmbeddingMath.cosineSimilarity(x, y);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"lengths must be equal\")) { logDimensionMismatch(x, y); return 0.0; }\n    throw e;\n}","preventionTips":["Re-embed the whole store whenever the embedding model changes.","Record expected dimensionality in config and validate vectors at ingestion."],"tags":["vector-math","dimension-mismatch","embedding"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}