{"record":{"id":"83c62442ef39a710","repo":"apache/cassandra","slug":"out-of-bounds-value-at-vector","errorCode":null,"errorMessage":"Out-of-bounds value at vector[","messagePattern":"Out-of-bounds value at vector\\[","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sai/disk/v1/vector/OnHeapGraph.java","lineNumber":251,"sourceCode":"\n        return bytesUsed;\n    }\n\n    // copied out of a Lucene PR -- hopefully committed soon\n    public static final float MAX_FLOAT32_COMPONENT = 1E17f;\n\n    public static void checkInBounds(float[] v)\n    {\n        for (int i = 0; i < v.length; i++)\n        {\n            if (!Float.isFinite(v[i]))\n            {\n                throw new IllegalArgumentException(\"non-finite value at vector[\" + i + \"]=\" + v[i]);\n            }\n\n            if (Math.abs(v[i]) > MAX_FLOAT32_COMPONENT)\n            {\n                throw new IllegalArgumentException(\"Out-of-bounds value at vector[\" + i + \"]=\" + v[i]);\n            }\n        }\n    }\n\n    public static void validateIndexable(float[] vector, VectorSimilarityFunction similarityFunction)\n    {\n        try\n        {\n            checkInBounds(vector);\n        }\n        catch (IllegalArgumentException e)\n        {\n            throw new InvalidRequestException(e.getMessage());\n        }\n\n        if (similarityFunction == VectorSimilarityFunction.COSINE)\n        {\n            for (int i = 0; i < vector.length; i++)","sourceCodeStart":233,"sourceCodeEnd":269,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/disk/v1/vector/OnHeapGraph.java#L233-L269","documentation":"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.","triggerScenarios":"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.","commonSituations":"Unnormalized embedding pipelines, client-side encoding bugs writing wrong byte order producing huge floats, or mixing vector dimension/scale conventions across applications.","solutions":["Normalize or rescale embeddings before writing so all components fit the allowed float32 magnitude","Validate vectors client-side (abs(component) <= MAX_FLOAT32_COMPONENT) before sending to Cassandra","Fix the embedding computation/serialization code that produced the oversized components","Locate and repair existing rows with out-of-range vectors, then rebuild the vector index"],"exampleFix":"// before\nfloat[] v = model.embed(input); // may contain huge components\nsink.accept(v);\n// after\nfloat[] v = model.embed(input);\nfor (int i = 0; i < v.length; i++)\n    if (Math.abs(v[i]) > MAX_FLOAT32_COMPONENT) throw new IllegalArgumentException(\"component \" + i + \" out of range\");\nsink.accept(v);","handlingStrategy":"validation","validationCode":"for (float f : vector)\n    if (Math.abs(f) > MAX_FLOAT32_COMPONENT) throw new IllegalArgumentException(\"vector component out of range: \" + f);","typeGuard":"boolean isWithinFloat32Bounds(float[] v) {\n    for (float f : v) if (Math.abs(f) > MAX_FLOAT32_COMPONENT) return false;\n    return true;\n}","tryCatchPattern":"try {\n    vectorIndex.upsert(id, vector);\n} catch (IllegalArgumentException e) {\n    logger.warn(\"Rejected out-of-range vector for id {}: {}\", id, e.getMessage());\n    normalizeAndRetry(vector);\n}","preventionTips":["Normalize embeddings before storing so components stay in a bounded range","Validate byte-order/encoding on the client before sending float vectors","Standardize vector scale conventions across all writing applications"],"tags":["cassandra","sai","vector-search","validation"],"backgroundTag":"value-out-of-range","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}