apache/cassandra · error · InvalidRequestException

Function ${name} doesn't support all-zero vectors.

Error message

Function ${name} doesn't support all-zero vectors.

What it means

The similarity function implementation executes the comparison after checking each float[] argument for all-zero content. Because an all-zero vector makes cosine similarity mathematically undefined (division by zero), when supportsZeroVectors is false the execute method rejects such inputs with this InvalidRequestException.

Source

Thrown at src/java/org/apache/cassandra/cql3/functions/VectorFcts.java:91

            {
                return new FunctionArguments(context,
                                             (v, b) -> type.composeAsFloat(b),
                                             (v, b) -> type.composeAsFloat(b));
            }

            @Override
            public ByteBuffer execute(Arguments arguments) throws InvalidRequestException
            {
                if (arguments.containsNulls())
                    return null;

                float[] v1 = arguments.get(0);
                float[] v2 = arguments.get(1);

                if (!supportsZeroVectors)
                {
                    if (isAllZero(v1) || isAllZero(v2))
                        throw new InvalidRequestException("Function " + name + " doesn't support all-zero vectors.");
                }

                return FloatType.instance.decompose(f.compare(v1, v2));
            }

            private boolean isAllZero(float[] v)
            {
                for (float f : v)
                    if (f != 0)
                        return false;
                return true;
            }
        };
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Ensure vectors are populated with real (non-all-zero) embeddings before comparing
2. Filter out rows with zero vectors in application code before issuing the query
3. Use similarity_dot_product or similarity_euclidean if a zero-vector operand is legitimate for your use case

Example fix

// before
SELECT similarity_cosine(embedding, vector[0.0, 0.0, 0.0]) FROM items; // all-zero query vector
// after
SELECT similarity_cosine(embedding, vector[0.12, -0.4, 0.9]) FROM items;

static boolean isAllZero(float[] v) {
    for (float f : v) if (f != 0.0f) return false;
    return true;
}
if (isAllZero(queryVector)) throw new IllegalArgumentException("zero vector not allowed for similarity_cosine");

try {
    ResultSet rs = session.execute(similarityQuery);
} catch (InvalidRequestException e) {
    if (e.getMessage().contains("doesn't support all-zero vectors")) {
        // fall back to dot product or skip the row
    }
}

When it happens

Trigger: Calling similarity_cosine (which disallows zero vectors) with an argument whose every float is 0.0, either as a literal vector[0.0, 0.0, ...] or read from a column holding a zero vector.

Common situations: Rows where a default/uninitialized embedding of all zeros was inserted; failed embedding generation producing empty vectors; users testing similarity functions with zero placeholders.

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

• All arguments must have the same vector dimensions
• %s doesn't support %s
• The padding argument for function %s should be single-charac
• Cannot specify more than one ANN ordering
• ANN ordering does not support any other ordering

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