apache/cassandra · error · IllegalArgumentException

Got overlapping ranges in replica groups:

Error message

Got overlapping ranges in replica groups: 

What it means

The ReplicaGroups constructor builds parallel sorted lists of token ranges and their replica endpoints. It validates that consecutive ranges in the sorted order do not overlap: if the previous range's right bound extends past the next range's left bound, it throws IllegalArgumentException, because replica groups must partition (not overlap) the token space.

Solutions

1. Fix the producer of the range map so ranges are non-overlapping and cover the ring exactly once
2. Normalize/merge overlapping ranges before constructing ReplicaGroups
3. Validate the input map by sorting ranges and checking prev.right <= next.left before calling the constructor
4. If caused by a replication strategy bug, regenerate placement data (e.g. rebuild metadata) with the corrected strategy

Example fix

// before
map.put(new Range<>(t(0), t(100)), ep1);
map.put(new Range<>(t(50), t(150)), ep2);  // overlap -> throws
// after
map.put(new Range<>(t(0), t(100)), ep1);
map.put(new Range<>(t(100), t(150)), ep2);

// validate before constructing
List<Range<Token>> sorted = ranges.stream().sorted(Comparator.comparing(r -> r.left)).collect(Collectors.toList());
for (int i = 1; i < sorted.size(); i++)
    if (sorted.get(i-1).right.compareTo(sorted.get(i).left) > 0) throw new IllegalArgumentException("Overlap: " + sorted.get(i-1) + " and " + sorted.get(i));

boolean rangesNonOverlapping(java.util.Collection<Range<Token>> rs) {
    Range<Token> prev = null;
    for (Range<Token> r : com.google.common.collect.ImmutableSortedMap.<Range<Token>,Object>naturalOrderKeys()) {}
    return true; // sort and compare consecutive right<=left bounds
}

try { new ReplicaGroups(map); } catch (IllegalArgumentException e) { // log offending map, fix range producer, rebuild }

When it happens

Trigger: Constructing ReplicaGroups from a map of (Range<Token> -> VersionedEndpoints.ForRange) where two ranges overlap, e.g. [0,100) and [50,150) present together.

Common situations: Bugs in custom placement/replication strategies that compute overlapping ranges; corrupted or hand-edited ownership metadata; merging partial range maps from different sources.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Addresses differ: !=
• Can only initialize cluster identifier during epoch
• Can't commit transformations when running in gossip mode…
• Can't finish migration, initiator=
• Can't ignore local host

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tcm/ownership/ReplicaGroups.java:102

            return 0;
        }
    };

    public static final Serializer serializer = new Serializer();
    public static final ReplicaGroups EMPTY = ReplicaGroups.builder().build();

    public final ImmutableList<Range<Token>> ranges;
    public final ImmutableList<VersionedEndpoints.ForRange> endpoints;

    private ReplicaGroups(Map<Range<Token>, VersionedEndpoints.ForRange> replicaGroups)
    {
        ImmutableList.Builder<Range<Token>> rangesBuilder = ImmutableList.builderWithExpectedSize(replicaGroups.size());
        ImmutableList.Builder<VersionedEndpoints.ForRange> endpointsBuilder = ImmutableList.builderWithExpectedSize(replicaGroups.size());
        Range<Token> prev = null;
        for (Map.Entry<Range<Token>, VersionedEndpoints.ForRange> entry : ImmutableSortedMap.copyOf(replicaGroups, Comparator.comparing(o -> o.left)).entrySet())
        {
            if (prev != null && prev.right.compareTo(entry.getKey().left) > 0 )
                throw new IllegalArgumentException("Got overlapping ranges in replica groups: " + replicaGroups);
            prev = entry.getKey();
            rangesBuilder.add(entry.getKey());
            endpointsBuilder.add(entry.getValue());
        }
        this.ranges = rangesBuilder.build();
        this.endpoints = endpointsBuilder.build();
    }

    private ReplicaGroups(ImmutableList<Range<Token>> ranges,
                         ImmutableList<VersionedEndpoints.ForRange> endpoints)
    {
        this.ranges = ranges;
        this.endpoints = endpoints;
    }

    /**
     * returns a copy of ranges sorted by the right token (`ranges` in this class is sorted by the left)
     */

View on GitHub (pinned to 88fd0f6a0e)