apache/cassandra · error · IllegalArgumentException

Postings must be sorted ascending, got

Error message

Postings must be sorted ascending, got [%s] after [%s]

What it means

PostingsWriter.writePosting() enforces that postings (rowids) arrive in strictly non-decreasing order, because the on-disk format stores delta-encoded values. A posting smaller than the previous one would produce a negative delta that cannot be encoded, so it fails fast with IllegalArgumentException.

Solutions

1. Ensure the rowid source is sorted ascending before writing postings.
2. Deduplicate the caller's iteration order (e.g. sort per-partition row ids).
3. If encountered during normal flush, it's an internal invariant breach — gather logs/version and report; rebuild the index in the meantime.

Example fix

// before
for (long id : unsortedIds) writer.writePosting(id);
// after
Arrays.sort(ids);
for (long id : ids) writer.writePosting(id);

for (int i = 1; i < ids.length; i++) if (ids[i] < ids[i-1]) throw new AssertionError("unsorted rowids");

try { writer.writePosting(p); } catch (IllegalArgumentException e) { log.error("Posting order violated", e); throw e; }

When it happens

Trigger: Calling writePosting (via write()) with posting < lastPosting, i.e. feeding rowids out of order during segment flush of an SAI posting list.

Common situations: Internal SAI bug where the row-id source (partition/row iterator) is not sorted; developers writing custom key-range iterators or replaying unsorted buffers see this.

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

• Clustering keys must be in ascending lexographical order
• CVV requires vectors to be added in ordinal order
• A storage-attached index cannot be created over multiple…
• An error occurred while scrubbing the partition with key
• Analysis options are not supported on primary key columns…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/index/sai/disk/v1/postings/PostingsWriter.java:217

        return summaryOffset;
    }

    public long getTotalPostings()
    {
        return totalPostings;
    }

    private void writePosting(long posting) throws IOException
    {
        if (lastPosting == Long.MIN_VALUE)
        {
            firstPosting = posting;
            deltaBuffer[bufferUpto++] = 0;
        }
        else
        {
            if (posting < lastPosting)
                throw new IllegalArgumentException(String.format(POSTINGS_MUST_BE_SORTED_ERROR_MSG, posting, lastPosting));
            long delta = posting - lastPosting;
            maxDelta = max(maxDelta, delta);
            deltaBuffer[bufferUpto++] = delta;
        }
        lastPosting = posting;

        if (bufferUpto == blockSize)
        {
            addBlockToSkipTable();
            writePostingsBlock();
            resetBlockCounters();
        }
    }

    private void finish() throws IOException
    {
        if (bufferUpto > 0)
        {

View on GitHub (pinned to 88fd0f6a0e)