apache/cassandra · error · InvalidRequestException

Zero vectors cannot be indexed or queried with cosine…

Error message

Zero vectors cannot be indexed or queried with cosine similarity

What it means

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.

Solutions

1. Replace zero vectors with real non-zero embeddings before writing
2. Add application-side validation that rejects all-zero vectors before INSERT
3. If a zero query vector is possible, check it client-side and return an empty result instead of querying
4. Use a different similarity function (e.g. euclidean) if zero vectors are legitimate data

Example fix

// before
float[] embedding = embed(text); // may return all zeros
session.execute(insert.bind(embedding));
// after
float[] embedding = embed(text);
boolean allZero = true;
for (float v : embedding) if (v != 0f) { allZero = false; break; }
if (allZero) throw new IllegalArgumentException("refusing to store zero vector");
session.execute(insert.bind(embedding));

public static boolean isZeroVector(float[] v) {
    if (v == null || v.length == 0) return true;
    for (float x : v) if (x != 0f) return false;
    return true;
}
// before insert/query: if (isZeroVector(vec)) reject or skip

boolean isIndexableVector(float[] v) { return v != null && v.length > 0 && !isZeroVector(v); }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• A storage-attached index cannot be created over multiple…
• All arguments must have the same vector dimensions
• Failed to retrieve target column for:
• Function doesn't support all-zero vectors.
• Invalid operator

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/8d16e5f4007b9de9. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/index/sai/disk/v1/vector/OnHeapGraph.java:274

    public static void validateIndexable(float[] vector, VectorSimilarityFunction similarityFunction)
    {
        try
        {
            checkInBounds(vector);
        }
        catch (IllegalArgumentException e)
        {
            throw new InvalidRequestException(e.getMessage());
        }

        if (similarityFunction == VectorSimilarityFunction.COSINE)
        {
            for (int i = 0; i < vector.length; i++)
            {
                if (vector[i] != 0)
                    return;
            }
            throw new InvalidRequestException("Zero vectors cannot be indexed or queried with cosine similarity");
        }
    }

    public Collection<T> keysFromOrdinal(int node)
    {
        return postingsByOrdinal.get(node).getPostings();
    }

    public float[] vectorForKey(T key)
    {
        if (vectorsByKey == null)
            throw new IllegalStateException("vectorsByKey is not initialized");
        return vectorsByKey.get(key);
    }

    public long remove(ByteBuffer term, T key)
    {
        assert term != null && term.remaining() != 0;

View on GitHub (pinned to 88fd0f6a0e)