apache/cassandra · error · IllegalStateException

Trying to stream locally. Range: in keyspace

Error message

Trying to stream locally. Range:  in keyspace 

What it means

validateRangeFetchMap throws this IllegalStateException if the computed streaming fetch plan assigns a range to be streamed from the local node itself. Streaming data from yourself would be a no-op and indicates a bug in the fetch-map computation or invalid metadata.

Solutions

1. Retry the operation after confirming token metadata is up to date (nodetool ring/status)
2. Report this as a bug — it is an internal invariant violation, not an expected user error
3. Ensure the node being bootstrapped/replaced does not already own the ranges (check system.local, system.peers, nodetool info ownership)
4. Restart the node to refresh its view of cluster metadata and retry

Example fix

// before: local endpoint appears in fetch map
Map<InetAddressAndPort, Multimap<Range<Token>, InetAddressAndPort>> workMap = streamer.workMap;
// after: filter/verify sources are remote before streaming
if (source.equals(FBUtilities.getBroadcastAddressAndPort()))
    throw new IllegalStateException("... "); // surfaced error -> fix metadata via nodetool resetlocal? no: refresh gossip
nodetool refreshpeers && nodetool status

// ensure token metadata is current before operations
// nodetool ring; confirm the local node does not already own the target ranges

try {
    result = streamer.workMap;
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Trying to stream locally")) {
        // refresh gossip/token metadata and retry; report bug if persistent
    }
}

When it happens

Trigger: Calling getOptimizedWorkMap when the range-fetch map produced by the allocator contains an entry whose key equals FBUtilities.getBroadcastAddressAndPort() for the given keyspace.

Common situations: Topology changes (bootstrap/replace/move) racing with metadata updates so the local node still appears as a replica/source; bugs or stale token metadata in the range computation.

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

• Trying to stream from wrong endpoint. Range: in keyspace …
• A node required to move the data consistently is down
• Can not start range streaming as all candidates
• Can't join the ring because bootstrap hasn't completed.
• Cannot send stream data messages for preview streaming…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/dht/RangeStreamer.java:669

            //Committing the cardinal sin of synthesizing a Replica, but it's ok because we assert earlier all of them
            //are full and optimized range fetch map doesn't support transient replication yet.
            wrapped.put(entry.getKey(), new FetchReplica(toFetch, fullReplica(entry.getKey(), entry.getValue())));
        }

        return wrapped;
    }

    /**
     * Verify that source returned for each range is correct
     */
    @VisibleForTesting
    static void validateRangeFetchMap(EndpointsByRange rangesWithSources, Multimap<InetAddressAndPort, Range<Token>> rangeFetchMapMap, String keyspace)
    {
        for (Map.Entry<InetAddressAndPort, Range<Token>> entry : rangeFetchMapMap.entries())
        {
            if(entry.getKey().equals(FBUtilities.getBroadcastAddressAndPort()))
            {
                throw new IllegalStateException("Trying to stream locally. Range: " + entry.getValue()
                                                + " in keyspace " + keyspace);
            }

            if (!rangesWithSources.get(entry.getValue()).endpoints().contains(entry.getKey()))
            {
                throw new IllegalStateException("Trying to stream from wrong endpoint. Range: " + entry.getValue()
                                                + " in keyspace " + keyspace + " from endpoint: " + entry.getKey());
            }

            logger.info("Streaming range {} from endpoint {} for keyspace {}", entry.getValue(), entry.getKey(), keyspace);
        }
    }

    // For testing purposes
    @VisibleForTesting
    Map<String, Multimap<InetAddressAndPort, FetchReplica>> toFetch()
    {
        return toFetch;

View on GitHub (pinned to 88fd0f6a0e)