apache/cassandra · error · InvalidRequestException

Function 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.

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
• A storage-attached index cannot be created over multiple…
• ANN ordering does not support any other ordering
• Attempted to read a range containing
• Can only unset '" + name + "'

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

Appendix: 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)