{"record":{"id":"8d16e5f4007b9de9","repo":"apache/cassandra","slug":"zero-vectors-cannot-be-indexed-or-queried-with-cos","errorCode":null,"errorMessage":"Zero vectors cannot be indexed or queried with cosine similarity","messagePattern":"Zero vectors cannot be indexed or queried with cosine similarity","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sai/disk/v1/vector/OnHeapGraph.java","lineNumber":274,"sourceCode":"    public static void validateIndexable(float[] vector, VectorSimilarityFunction similarityFunction)\n    {\n        try\n        {\n            checkInBounds(vector);\n        }\n        catch (IllegalArgumentException e)\n        {\n            throw new InvalidRequestException(e.getMessage());\n        }\n\n        if (similarityFunction == VectorSimilarityFunction.COSINE)\n        {\n            for (int i = 0; i < vector.length; i++)\n            {\n                if (vector[i] != 0)\n                    return;\n            }\n            throw new InvalidRequestException(\"Zero vectors cannot be indexed or queried with cosine similarity\");\n        }\n    }\n\n    public Collection<T> keysFromOrdinal(int node)\n    {\n        return postingsByOrdinal.get(node).getPostings();\n    }\n\n    public float[] vectorForKey(T key)\n    {\n        if (vectorsByKey == null)\n            throw new IllegalStateException(\"vectorsByKey is not initialized\");\n        return vectorsByKey.get(key);\n    }\n\n    public long remove(ByteBuffer term, T key)\n    {\n        assert term != null && term.remaining() != 0;","sourceCodeStart":256,"sourceCodeEnd":292,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/disk/v1/vector/OnHeapGraph.java#L256-L292","documentation":"OnHeapGraph validates vectors before indexing or searching when cosine similarity is used. A zero vector has no direction, so cosine similarity is undefined (division by zero norm), and Cassandra refuses to index or query with it. The check iterates the float array and throws InvalidRequestException if every component is 0.","triggerScenarios":"Inserting a row whose vector column is all zeros ([0,0,...,0]) into a table with a cosine-similarity SAI vector index, or issuing an ANN search with an all-zero query vector; validateIndexable is invoked from both add and search paths.","commonSituations":"Default-initialized or placeholder embeddings accidentally written (e.g. an embedding call returned zeros on failure); sending a blank/empty text to an embedding model that yields zeros; testing with dummy vectors of zeros.","solutions":["Replace zero vectors with real non-zero embeddings before writing","Add application-side validation that rejects all-zero vectors before INSERT","If a zero query vector is possible, check it client-side and return an empty result instead of querying","Use a different similarity function (e.g. euclidean) if zero vectors are legitimate data"],"exampleFix":"// before\nfloat[] embedding = embed(text); // may return all zeros\nsession.execute(insert.bind(embedding));\n// after\nfloat[] embedding = embed(text);\nboolean allZero = true;\nfor (float v : embedding) if (v != 0f) { allZero = false; break; }\nif (allZero) throw new IllegalArgumentException(\"refusing to store zero vector\");\nsession.execute(insert.bind(embedding));","handlingStrategy":"validation","validationCode":"public static boolean isZeroVector(float[] v) {\n    if (v == null || v.length == 0) return true;\n    for (float x : v) if (x != 0f) return false;\n    return true;\n}\n// before insert/query: if (isZeroVector(vec)) reject or skip","typeGuard":"boolean isIndexableVector(float[] v) { return v != null && v.length > 0 && !isZeroVector(v); }","tryCatchPattern":null,"preventionTips":["Validate embeddings for non-zero content before writing","Handle embedding-service failures that return zero arrays","Pick similarity functions matching your data semantics"],"tags":["vector-search","sai","invalid-request","cosine-similarity"],"backgroundTag":"invalid-argument-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}