apache/cassandra · error · IllegalArgumentException

Ranges supplied to SSTableSimpleScanner must be…

Error message

Ranges supplied to SSTableSimpleScanner must be non-overlapping and in ascending order.

What it means

SSTableSimpleScanner's advanceRange() walks a caller-supplied set of key ranges mapped to file positions; it requires them to be non-overlapping and in ascending order of position. When the next range's lower position is less than the current range's end position, it throws IllegalArgumentException because scanning would double-read or rewind within the data file.

Solutions

Sort the ranges in ascending order before constructing the scanner
Merge/eliminate overlapping ranges into disjoint segments before passing them in
Validate the range list programmatically prior to scanner creation (assert non-overlap)
Regenerate the ranges from the correct source (e.g. proper token range splitting)

Example fix

// before: raw possibly overlapping ranges
new SSTableSimpleScanner(sstable, ranges);
// after: sort and merge first
List<PartitionPositionBounds> fixed = mergeOverlapping(
    ranges.stream().sorted(Comparator.comparingLong(r -> r.lowerPosition)).collect(Collectors.toList()));
new SSTableSimpleScanner(sstable, fixed);

Defensive patterns

Strategy: validation

Validate before calling

// validate ranges before constructing the scanner
long prevEnd = -1;
for (PartitionPositionBounds r : ranges) {
    if (r.lowerPosition <= prevEnd) throw new IllegalArgumentException("overlapping/out-of-order ranges");
    prevEnd = r.upperPosition;
}

Try / catch

try { scanner.hasNext() / scanner.next(); }
catch (IllegalArgumentException e) {
    if (e.getMessage().contains("non-overlapping and in ascending order")) {
        ranges = sortAndMerge(ranges); // rebuild scanner with fixed ranges
    } else throw e;
}

Prevention

Sort and merge ranges before creating SSTableSimpleScanner
Derive ranges from non-overlapping token range splitting logic
Unit-test range generation code for overlap conditions
Assert range ordering in tooling before scanning

When it happens

Trigger: Constructing SSTableSimpleScanner with a collection of ranges that overlap (currentEndPosition > nextRange.lowerPosition) or are out of ascending order; the failure surfaces on advanceRange() when hasNext() advances past the first range.

Common situations: Custom bulk-read/sstable-scanning tools computing ranges from faulty logic; intersecting token ranges from duplicated token assignments; hand-built range lists not sorted before use.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/io/sstable/format/SSTableSimpleScanner.java:182

        if (dfile.getFilePointer() < currentEndPosition)
            return true;

        return advanceRange();
    }

    boolean advanceRange()
    {
        try
        {
            if (!rangeIterator.hasNext())
                return false;

            bytesScannedInPreviousRanges += currentEndPosition - currentStartPosition;

            PartitionPositionBounds nextRange = rangeIterator.next();
            if (currentEndPosition > nextRange.lowerPosition)
                throw new IllegalArgumentException("Ranges supplied to SSTableSimpleScanner must be non-overlapping and in ascending order.");

            currentEndPosition = nextRange.upperPosition;
            currentStartPosition = nextRange.lowerPosition;
            dfile.seek(currentStartPosition);
            return true;
        }
        catch (CorruptSSTableException e)
        {
            sstable.markSuspect();
            throw e;
        }
        catch (IOError e)
        {
            if (e.getCause() instanceof IOException)
            {
                sstable.markSuspect();
                throw new CorruptSSTableException((Exception)e.getCause(), sstable.getFilename());
            }

View on GitHub (pinned to 88fd0f6a0e)