apache/cassandra · error · IllegalArgumentException

non-finite value at vector[

Error message

non-finite value at vector[

What it means

IllegalArgumentException thrown by OnHeapGraph.checkInBounds when a float vector component is NaN or +/-Infinity. Vector similarity computations are undefined for non-finite components, so the graph index validates every vector before insertion. The message includes the component index and value.

Source

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

        // postings list already exists, just add the new key (if it's not already in the list)
        if (postings.add(key))
        {
            bytesUsed += VectorPostings.bytesPerPosting();
        }

        return bytesUsed;
    }

    // copied out of a Lucene PR -- hopefully committed soon
    public static final float MAX_FLOAT32_COMPONENT = 1E17f;

    public static void checkInBounds(float[] v)
    {
        for (int i = 0; i < v.length; i++)
        {
            if (!Float.isFinite(v[i]))
            {
                throw new IllegalArgumentException("non-finite value at vector[" + i + "]=" + v[i]);
            }

            if (Math.abs(v[i]) > MAX_FLOAT32_COMPONENT)
            {
                throw new IllegalArgumentException("Out-of-bounds value at vector[" + i + "]=" + v[i]);
            }
        }
    }

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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Validate/sanitize the embedding output before writing: replace or reject NaN/Infinity components
2. Check the embedding generation code for divide-by-zero, log(0), or overflow producing non-finite floats
3. Reject or fix the offending write at the application layer before sending to Cassandra
4. If reading existing data, identify and repair the rows containing non-finite vectors

Example fix

// before
float[] v = computeEmbedding(input);
sink.accept(v);
// after
float[] v = computeEmbedding(input);
for (float f : v)
    if (!Float.isFinite(f)) throw new IllegalArgumentException("embedding contains non-finite value");
sink.accept(v);

for (float f : vector)
    if (!Float.isFinite(f)) throw new IllegalArgumentException("vector contains non-finite component: " + f);

boolean isFiniteVector(float[] v) {
    for (float f : v) if (!Float.isFinite(f)) return false;
    return true;
}

try {
    vectorIndex.upsert(id, vector);
} catch (IllegalArgumentException e) {
    logger.warn("Rejected non-finite vector for id {}: {}", id, e.getMessage());
    sanitizeOrReject(vector);
}

When it happens

Trigger: Inserting or indexing a vector produced from NaN/Infinity, e.g. dividing by zero while computing embeddings, decomposing malformed client-provided bytes into floats, or uninitialized float arrays.

Common situations: Client applications sending float2 vectors built from unvalidated model output, missing values encoded as NaN in embeddings, or float overflow (values beyond float32 range) during embedding computation.

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

• Out-of-bounds value at vector[
• Empty value for boolean option ''
• Illegal value for boolean option '':
• Unsupported expression during ANN index query:
• REVOKE operation is not supported by AllowAllAuthorizer

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