apache/cassandra · error · IllegalArgumentException

CVV requires vectors to be added in ordinal order

Error message

CVV requires vectors to be added in ordinal order (%d given, expected %d)

What it means

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.

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

Example fix

// before
cvv.add(vectorOrdinal, buffer); // vectorOrdinal from a stale counter
// after
assert vectorOrdinal == cvv.size() : "out-of-order ordinal " + vectorOrdinal;
cvv.add(cvv.size(), buffer); // derive ordinal from current size

Defensive patterns

Strategy: validation

Validate before calling

if (ordinal != cvv.size())
    throw new IllegalStateException("CVV append out of order: got " + ordinal + ", expected " + cvv.size());

Type guard

boolean isNextOrdinal(CompactionVectorValues cvv, int ordinal) {
    return ordinal == cvv.size();
}

Try / catch

try {
    cvv.add(ordinal, buffer);
} catch (IllegalArgumentException e) {
    logger.error("Vector append skipped/duplicated at ordinal {}: {}", ordinal, e.getMessage());
    restartCompactionFromLastCheckpoint();
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/index/sai/disk/v1/vector/CompactionVectorValues.java:67

    }

    @Override
    public int dimension()
    {
        return dimension;
    }

    @Override
    public float[] vectorValue(int i)
    {
        return type.composeAsFloat(values.get(i));
    }

    /** return approximate bytes used by the new vector */
    public long add(int ordinal, ByteBuffer value)
    {
        if (ordinal != values.size())
            throw new IllegalArgumentException(String.format("CVV requires vectors to be added in ordinal order (%d given, expected %d)",
                                                             ordinal, values.size()));
        values.add(value);
        return RamEstimation.concurrentHashMapRamUsed(1) + oneVectorBytesUsed();
    }

    @Override
    public CompactionVectorValues copy()
    {
        return this;
    }

    public long write(SequentialWriter writer) throws IOException
    {
        writer.writeInt(size());
        writer.writeInt(dimension());

        for (int i = 0; i < size(); i++) {
            ByteBuffer bb = values.get(i);

View on GitHub (pinned to 88fd0f6a0e)