{"record":{"id":"551d6498d0e43052","repo":"apache/cassandra","slug":"cvv-requires-vectors-to-be-added-in-ordinal-order","errorCode":null,"errorMessage":"CVV requires vectors to be added in ordinal order (%d given, expected %d)","messagePattern":"CVV requires vectors to be added in ordinal order \\((.+?) given, expected (.+?)\\)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sai/disk/v1/vector/CompactionVectorValues.java","lineNumber":67,"sourceCode":"    }\n\n    @Override\n    public int dimension()\n    {\n        return dimension;\n    }\n\n    @Override\n    public float[] vectorValue(int i)\n    {\n        return type.composeAsFloat(values.get(i));\n    }\n\n    /** return approximate bytes used by the new vector */\n    public long add(int ordinal, ByteBuffer value)\n    {\n        if (ordinal != values.size())\n            throw new IllegalArgumentException(String.format(\"CVV requires vectors to be added in ordinal order (%d given, expected %d)\",\n                                                             ordinal, values.size()));\n        values.add(value);\n        return RamEstimation.concurrentHashMapRamUsed(1) + oneVectorBytesUsed();\n    }\n\n    @Override\n    public CompactionVectorValues copy()\n    {\n        return this;\n    }\n\n    public long write(SequentialWriter writer) throws IOException\n    {\n        writer.writeInt(size());\n        writer.writeInt(dimension());\n\n        for (int i = 0; i < size(); i++) {\n            ByteBuffer bb = values.get(i);","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/disk/v1/vector/CompactionVectorValues.java#L49-L85","documentation":"IllegalArgumentException thrown by CompactionVectorValues.add when vectors are appended with an ordinal that is not the next sequential one. CVV is an append-only structure during compaction and requires ordinals 0,1,2,...; out-of-order or skipped ordinals would corrupt the ordinal-to-vector mapping.","triggerScenarios":"Calling add(ordinal, value) with ordinal != values.size(), e.g. adding ordinal 3 before ordinal 2, retrying an already-added ordinal, or parallel writers appending without coordination.","commonSituations":"Custom compaction/repair code writing vectors out of order, resumed compaction restarting at the wrong ordinal, or test harnesses simulating writes with wrong sequence numbers.","solutions":["Track the next expected ordinal and always add vectors sequentially (0..n-1)","If resuming an interrupted build, recompute the current size and start from values.size()","Remove duplicate/retry appends or make add idempotent at the call site","If concurrent writers are involved, serialize appends with a lock or single-writer thread"],"exampleFix":"// before\ncvv.add(vectorOrdinal, buffer); // vectorOrdinal from a stale counter\n// after\nassert vectorOrdinal == cvv.size() : \"out-of-order ordinal \" + vectorOrdinal;\ncvv.add(cvv.size(), buffer); // derive ordinal from current size","handlingStrategy":"validation","validationCode":"if (ordinal != cvv.size())\n    throw new IllegalStateException(\"CVV append out of order: got \" + ordinal + \", expected \" + cvv.size());","typeGuard":"boolean isNextOrdinal(CompactionVectorValues cvv, int ordinal) {\n    return ordinal == cvv.size();\n}","tryCatchPattern":"try {\n    cvv.add(ordinal, buffer);\n} catch (IllegalArgumentException e) {\n    logger.error(\"Vector append skipped/duplicated at ordinal {}: {}\", ordinal, e.getMessage());\n    restartCompactionFromLastCheckpoint();\n}","preventionTips":["Derive the ordinal from the collection size instead of an external counter","Use a single writer thread or lock for vector appends during compaction","Persist a checkpoint of the last written ordinal for resumable builds"],"tags":["cassandra","sai","vector-compaction","ordering"],"backgroundTag":"invalid-state-transition","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}