apache/cassandra · error · IllegalArgumentException

Requested range intersects a local range ( ) but is not…

Error message

Requested range %s intersects a local range (%s) but is not fully contained in one; this would lead to imprecise repair. keyspace: %s

What it means

getNeighbors validates that every requested repair range either fully contains a local token range or does not intersect it at all. A requested range that partially overlaps a local range would produce an imprecise repair (some subranges repaired, others not), so Cassandra rejects it with IllegalArgumentException instead of silently repairing incorrectly.

Solutions

  1. Align -st/-et with actual ring range boundaries (use nodetool ring / system.local token metadata)
  2. Repair the full local range by not passing -st/-et, or use -pr
  3. Compute requested ranges from the local ranges of the node rather than arbitrary splits

Example fix

// before
nodetool repair -st 100 -et 200 keyspace1  // 200 cuts a local range in half
// after
nodetool repair -st 100 -et 350 keyspace1   // end aligned to range boundary
Defensive patterns

Strategy: validation

Validate before calling

// verify the requested range is contained in a single local range before repair
List<Range<Token>> localRanges = storageService.getLocalRanges(keyspace);
boolean ok = localRanges.stream().anyMatch(r -> r.contains(requested));

Try / catch

try { repairNeighbors = ActiveRepairService.instance.getNeighbors(...); }
catch (IllegalArgumentException e) { log.error("misaligned -st/-et range", e); }

Prevention

When it happens

Trigger: Calling nodetool repair (or StorageService.repair) with -st/-et start/end tokens such that the range [st,et] intersects but does not contain a local primary range, e.g. splitting a repair range mid-token-range.

Common situations: Operators computing token ranges for parallelized repair with incorrect boundaries; tools that chunk the token space without respecting ring range boundaries (range boundaries must align with local ranges).

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/5c2bc5d20de36f9e. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/service/ActiveRepairService.java:598

     * @param keyspaceLocalRanges local-range for given keyspaceName
     * @param toRepair            token to repair
     * @return neighbors with whom we share the provided range
     */
    public EndpointsForRange getNeighbors(String keyspaceName, Iterable<Range<Token>> keyspaceLocalRanges, Range<Token> toRepair)
    {
        StorageService ss = StorageService.instance;
        EndpointsByRange replicaSets = ss.getRangeToAddressMap(keyspaceName);
        Range<Token> rangeSuperSet = null;
        for (Range<Token> range : keyspaceLocalRanges)
        {
            if (range.contains(toRepair))
            {
                rangeSuperSet = range;
                break;
            }
            else if (range.intersects(toRepair))
            {
                throw new IllegalArgumentException(String.format("Requested range %s intersects a local range (%s) " +
                                                                 "but is not fully contained in one; this would lead to " +
                                                                 "imprecise repair. keyspace: %s", toRepair, range, keyspaceName));
            }
        }
        if (rangeSuperSet == null || !replicaSets.containsKey(rangeSuperSet))
            return EndpointsForRange.empty(toRepair);

        // same as withoutSelf(), but done this way for testing
        return replicaSets.get(rangeSuperSet).filter(r -> !ctx.broadcastAddressAndPort().equals(r.endpoint()));
    }


    /**
     * Return all of the neighbors in the listed data center or host lists
     *
     * @param toRepair            token to repair
     * @param dataCenters         the data centers to involve in the repair
     * @return neighbors with whom we share the provided range

View on GitHub (pinned to 88fd0f6a0e)