apache/cassandra · error · IllegalArgumentException

Clustering keys must be in ascending lexographical order

Error message

Clustering keys must be in ascending lexographical order

What it means

KeyStoreWriter.add() requires that, when writing clustering-key-scope keys (clustering && inPartition), each BytesRef key is strictly greater than the previous one. Keys are written into a shared trie/blocks structure that relies on sorted order; an out-of-order key would make lookups and prefix decoding incorrect. The message (note the 'lexographical' typo) is thrown as IllegalArgumentException.

Solutions

Ensure keys are added in ascending order — sort the batch before calling add().
If duplicates are expected, skip keys equal to the previous key before writing.
If seen during normal flush, it indicates internal corruption — report with the Cassandra version and rebuild the index.

Example fix

// before
writer.add(key2);
writer.add(key1); // throws if key1 <= key2
// after
keys.sort(comparator);
for (BytesRef k : keys) writer.add(k);

Defensive patterns

Strategy: validation

Validate before calling

if (prevKey != null && compareKeys(nextKey, prevKey) <= 0) skipOrSort(nextKey);

Try / catch

try { writer.add(keyRef); } catch (IllegalArgumentException e) { log.error("Unsorted clustering key", e); throw e; }

Prevention

Sort keys (or use an already-sorted source iterator) before writing.
Skip duplicates equal to the previous key.

When it happens

Trigger: Adding clustering keys where compareKeys(keyRef, prevKey) <= 0, i.e. equal or descending order, during segment flush of a partition-scoped SAI key store.

Common situations: Internal SAI bug or corrupted memtable ordering during flush; developers hitting this are usually instrumenting KeyStoreWriter directly with unsorted keys.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/index/sai/disk/v1/keystore/KeyStoreWriter.java:134

    }

    /**
     * Appends a key at the end of the sequence.
     *
     * @throws IOException if write to disk fails
     * @throws IllegalArgumentException if the key is not greater than the previous added key
     */
    public void add(final @Nonnull ByteComparable key) throws IOException
    {
        tempKey.clear();
        copyBytes(key, tempKey);

        BytesRef keyRef = tempKey.get();

        if (clustering && inPartition)
        {
            if (compareKeys(keyRef, prevKey.get()) <= 0)
                throw new IllegalArgumentException("Clustering keys must be in ascending lexographical order");
        }

        inPartition = true;

        writeKey(keyRef);

        maxKeyLength = Math.max(maxKeyLength, keyRef.length);

        BytesRefBuilder temp = this.tempKey;
        this.tempKey = this.prevKey;
        this.prevKey = temp;

        pointId++;
    }

    private void writeKey(BytesRef key) throws IOException
    {
        if ((pointId & blockMask) == 0)

View on GitHub (pinned to 88fd0f6a0e)