apache/cassandra · error · RuntimeException

Key is not contained in the given ranges

Error message

Key  is not contained in the given ranges

What it means

The RangeOwnHelper.Validator.validate method throws when a DecoratedKey (or token) is not contained in any of the ranges supplied to the verifier. It is a sanity check used by verifyOwnedRanges during `nodetool verify` with owned-ranges checking: every key visited must belong to a range this node owns.

Source

Thrown at src/java/org/apache/cassandra/io/sstable/format/SortedTableVerifier.java:445

        public RangeOwnHelper(List<Range<Token>> normalizedRanges)
        {
            this.normalizedRanges = normalizedRanges;
            Range.assertNormalized(normalizedRanges);
        }

        /**
         * check if the given key is contained in any of the given ranges
         * <p>
         * Must be called in sorted order - key should be increasing
         *
         * @param key the key
         * @throws RuntimeException if the key is not contained
         */
        public void validate(DecoratedKey key)
        {
            if (!check(key))
                throw new RuntimeException("Key " + key + " is not contained in the given ranges");
        }

        /**
         * check if the given key is contained in any of the given ranges
         * <p>
         * Must be called in sorted order - key should be increasing
         *
         * @param key the key
         * @return boolean
         */
        public boolean check(DecoratedKey key)
        {
            assert lastKey == null || key.compareTo(lastKey) > 0;
            lastKey = key;

            if (normalizedRanges.isEmpty()) // handle tests etc. where we don't have any ranges
                return true;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Re-run verify after gossip/token ring is stable so ranges are computed consistently.
  2. Run repair after topology changes so keys outside owned ranges are streamed to their new owners.
  3. In tests/tooling, include the key's range in the range list passed to RangeOwnHelper (use Range.normalize/build from the key's token).
  4. If using vnodes/multi-DC, ensure token metadata has fully propagated before verification.

Example fix

// before: validate with ranges that don't cover the key
Token tk = key.getToken(); // token outside ranges
helper.validator().validate(key); // throws
// after: build ranges from actual ownership
List<Range<Token>> ranges = Range.normalize(ownershipRangesFor(localToken));
RangeOwnHelper helper = new RangeOwnHelper(ranges);
helper.validator().validate(key);
Defensive patterns

Strategy: validation

Validate before calling

// Java: ensure ranges cover the key before validate
Range<Token> r = primaryRangeFor(key.getToken());
if (ranges.stream().noneMatch(x -> x.contains(key.getToken())))
    throw new IllegalArgumentException("Range list does not cover token " + key.getToken());

Try / catch

try {
    validator.validate(key);
} catch (RuntimeException e) {
    logger.warn("Key outside owned ranges; refresh token metadata and retry", e);
}

Prevention

When it happens

Trigger: Calling verify with owned-ranges checking when a visited partition key falls outside all provided ranges — e.g. token ownership changed between ring updates, ranges computed against a stale token metadata, or in tests calling validate() with a key outside the configured ranges.

Common situations: Topology changes mid-verify (node joining/leaving alters owned ranges); manually constructed range lists in tooling/tests (testRangeOwnHelper*) that omit the key's range; operating on a keyspace whose data predates a rebalance.

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