apache/cassandra · error · IllegalArgumentException

Out-of-bounds value at vector[

Error message

Out-of-bounds value at vector[

What it means

IllegalArgumentException thrown by OnHeapGraph.checkInBounds when a vector component's absolute value exceeds MAX_FLOAT32_COMPONENT. Extremely large components degrade similarity math and indicate bad input data, so the graph index rejects vectors out of the allowed float32 magnitude range before indexing. The message includes the component index and value.

Source

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

        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());
        }

        if (similarityFunction == VectorSimilarityFunction.COSINE)
        {
            for (int i = 0; i < vector.length; i++)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Normalize or rescale embeddings before writing so all components fit the allowed float32 magnitude
2. Validate vectors client-side (abs(component) <= MAX_FLOAT32_COMPONENT) before sending to Cassandra
3. Fix the embedding computation/serialization code that produced the oversized components
4. Locate and repair existing rows with out-of-range vectors, then rebuild the vector index

Example fix

// before
float[] v = model.embed(input); // may contain huge components
sink.accept(v);
// after
float[] v = model.embed(input);
for (int i = 0; i < v.length; i++)
    if (Math.abs(v[i]) > MAX_FLOAT32_COMPONENT) throw new IllegalArgumentException("component " + i + " out of range");
sink.accept(v);

for (float f : vector)
    if (Math.abs(f) > MAX_FLOAT32_COMPONENT) throw new IllegalArgumentException("vector component out of range: " + f);

boolean isWithinFloat32Bounds(float[] v) {
    for (float f : v) if (Math.abs(f) > MAX_FLOAT32_COMPONENT) return false;
    return true;
}

try {
    vectorIndex.upsert(id, vector);
} catch (IllegalArgumentException e) {
    logger.warn("Rejected out-of-range vector for id {}: {}", id, e.getMessage());
    normalizeAndRetry(vector);
}

When it happens

Trigger: Indexing a vector whose |component| > MAX_FLOAT32_COMPONENT, e.g. embeddings computed without normalization, float64 values cast to float32 with overflow-scale magnitudes, or corrupted float bytes decomposed into huge values.

Common situations: Unnormalized embedding pipelines, client-side encoding bugs writing wrong byte order producing huge floats, or mixing vector dimension/scale conventions across applications.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• non-finite 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/83c62442ef39a710. Report an issue: GitHub.