{"record":{"id":"619c11770e81804f","repo":"spring-projects/spring-ai","slug":"vectors-must-not-be-null","errorCode":null,"errorMessage":"Vectors must not be null","messagePattern":"Vectors must not be null","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/SimpleVectorStore.java","lineNumber":272,"sourceCode":"\n\t@Override\n\tpublic VectorStoreObservationContext.Builder createObservationContextBuilder(String operationName) {\n\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) {","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/SimpleVectorStore.java#L254-L290","documentation":"EmbeddingMath.cosineSimilarity throws a RuntimeException 'Vectors must not be null' when either input float[] is null. Unlike the length check, this guard uses RuntimeException rather than IllegalArgumentException.","triggerScenarios":"Passing a null embedding to cosineSimilarity, typically when an embedding call failed or returned null upstream, or comparing against a document whose vector was never computed.","commonSituations":"EmbeddingModel returning null on failure; deserialized stores with missing vectors; optional lookups yielding null before similarity computation.","solutions":["Null-check both vectors before calling cosineSimilarity.","Ensure embeddings are generated (and non-null) for every document before similarity ranking.","Prefer Objects.requireNonNull early in your pipeline to fail at the source."],"exampleFix":"// before\ndouble s = EmbeddingMath.cosineSimilarity(queryVec, docVec); // docVec may be null\n\n// after\nif (queryVec != null && docVec != null) {\n    double s = EmbeddingMath.cosineSimilarity(queryVec, docVec);\n}","handlingStrategy":"validation","validationCode":"if (vectorX == null || vectorY == null) {\n    throw new IllegalArgumentException(\"embeddings must be computed before similarity\");\n}\ndouble s = EmbeddingMath.cosineSimilarity(vectorX, vectorY);","typeGuard":"static boolean hasEmbedding(float[] v) { return v != null && v.length > 0; }","tryCatchPattern":"try {\n    return EmbeddingMath.cosineSimilarity(x, y);\n} catch (RuntimeException e) {\n    if (\"Vectors must not be null\".equals(e.getMessage())) { return 0.0; }\n    throw e;\n}","preventionTips":["Generate embeddings eagerly at ingestion, never lazily at comparison time.","Treat null embeddings as pipeline failures, not similarity inputs."],"tags":["vector-math","null-check","embedding"],"backgroundTag":"null-argument","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"}