apache/cassandra · error · IllegalStateException

Trying to stream from wrong endpoint. Range: in keyspace …

Error message

Trying to stream from wrong endpoint. Range:  in keyspace  from endpoint: 

What it means

validateRangeFetchMap throws this IllegalStateException when a range in the fetch plan is assigned to a source endpoint that was not among the validated sources (rangesWithSources) for that range in the given keyspace. It is an internal consistency check ensuring streaming only happens from legitimate replicas.

Solutions

1. Retry streaming after topology stabilizes (nodetool status shows all Up/Normal)
2. Report as a bug: the fetch-map builder selected an endpoint outside the validated source set
3. Refresh cluster metadata (restart the node or nodetool gossip file inspection) to clear stale token maps
4. Check for concurrent bootstrap/decommission/replace operations and serialize them

Example fix

// before: streaming attempt fails validation
nodetool move <token>
// after: ensure no concurrent topology ops, then retry
nodetool status   # all nodes Up/Normal, no leavings
nodetool move <token>

// verify chosen source endpoints are natural replicas before streaming
// cross-check endpoints with token metadata: StorageService.instance.getNaturalEndpoints(...).contains(source)

try {
    result = streamer.getOptimizedWorkMap();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Trying to stream from wrong endpoint")) {
        // refresh metadata and retry; serialize topology operations
    }
}

When it happens

Trigger: Calling getOptimizedWorkMap when the rangeFetchMapMap pairs a range with an endpoint not present in rangesWithSources.get(range).endpoints(), i.e. a source selected outside the computed candidate set.

Common situations: Concurrent topology changes making the chosen endpoint stale between candidate computation and validation; custom/patched load-balancing or allocation logic returning non-replica endpoints; corrupt token metadata.

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 locally. 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/4ee464eb351ec471. Report an issue: GitHub.

Appendix: source

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

    }

    /**
     * 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;
    }

    public StreamResultFuture fetchAsync()
    {
        toFetch.forEach((keyspace, sources) -> {
            logger.debug("Keyspace {} Sources {}", keyspace, sources);

View on GitHub (pinned to 88fd0f6a0e)