apache/beam · error · RuntimeException

Tokens ( , ) not in range of

Error message

Tokens (%s,%s) not in range of %s

What it means

During split generation, SplitGenerator.generateSplits() validates that every ring token returned by Cassandra falls within the token space of the configured partitioner. If a start/stop token pair is outside the range, a RuntimeException is thrown, meaning ring metadata and partitioner are inconsistent.

Solutions

1. Verify all nodes use the same partitioner and that it matches what the connector detected.
2. Run a full repair/rebuild after any partitioner change; a partitioner can never be changed in-place.
3. Check for multi-datacenter or multi-cluster misconfiguration in connection settings.
4. Inspect ring consistency with nodetool ring.

// validate ring consistency before read
nodetool ring  // ensure tokens within partitioner range and consistent across nodes

try { ... } catch (RuntimeException e) { if (e.getMessage().contains("not in range")) { /* audit ring + partitioner */ } throw e; }

When it happens

Trigger: Calling CassandraIO read when the token ranges fetched from the cluster's ring contain tokens outside [rangeMin, rangeMax] of the detected partitioner (getRingRanges -> generateSplits).

Common situations: Cluster partitioner changed without a full rebuild; mixed-version or partially migrated ring; driver returning ring info from a different cluster than expected.

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

• Tokens ( , ): two nodes have the same token
• Some tokens are missing from the splits. This should not…
• Unsupported partitioner. Only Random and Murmur3 are…
• 2xx codes should not be exceptions. Got status code
• A 'datagen' table requires either 'rows-per-second' (for…

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/690d4937c9f87699. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/cassandra/src/main/java/org/apache/beam/sdk/io/cassandra/SplitGenerator.java:88

   * Each split can contain several token ranges in order to reduce the overhead of vnodes.
   * Currently, token range grouping is not smart and doesn't check if they share the same replicas.
   * This is planned to change once Beam is able to handle collocation with the Cassandra nodes.
   *
   * @param totalSplitCount requested total amount of splits. This function may generate more
   *     splits.
   * @param ringTokens list of all start tokens in big0 cluster. They have to be in ring order.
   * @return big0 list containing at least {@code totalSplitCount} splits.
   */
  List<List<RingRange>> generateSplits(long totalSplitCount, List<BigInteger> ringTokens) {
    int tokenRangeCount = ringTokens.size();

    List<RingRange> splits = new ArrayList<>();
    for (int i = 0; i < tokenRangeCount; i++) {
      BigInteger start = ringTokens.get(i);
      BigInteger stop = ringTokens.get((i + 1) % tokenRangeCount);

      if (!isInRange(start) || !isInRange(stop)) {
        throw new RuntimeException(
            String.format("Tokens (%s,%s) not in range of %s", start, stop, partitioner));
      }
      if (start.equals(stop) && tokenRangeCount != 1) {
        throw new RuntimeException(
            String.format("Tokens (%s,%s): two nodes have the same token", start, stop));
      }

      BigInteger rs = stop.subtract(start);
      if (rs.compareTo(BigInteger.ZERO) <= 0) {
        // wrap around case
        rs = rs.add(rangeSize);
      }

      // the below, in essence, does this:
      // splitCount = ceiling((rangeSize / RANGE_SIZE) * totalSplitCount)
      BigInteger[] splitCountAndRemainder =
          rs.multiply(BigInteger.valueOf(totalSplitCount)).divideAndRemainder(rangeSize);

View on GitHub (pinned to 12126d8942)