apache/cassandra · warning · IllegalArgumentException

Unknown endpoint %s

Error message

Unknown endpoint %s

What it means

IllegalArgumentException from the deprecated (CEP-21) getLocalPrimaryRangeForEndpoint: the supplied endpoint address cannot be resolved to a peer NodeId in the current ClusterMetadata directory, meaning the node is unknown to the cluster (not part of membership).

Source

Thrown at src/java/org/apache/cassandra/service/StorageService.java:452

    @Deprecated(since = "CEP-21")
    public Collection<Range<Token>> getPrimaryRangesForEndpoint(String keyspace, InetAddressAndPort ep)
    {
        return TokenRingUtils.getPrimaryRangesForEndpoint(keyspace, ep);
    }

    @Deprecated(since = "CEP-21")
    public Collection<Range<Token>> getPrimaryRangesWithinDC(String keyspace)
    {
        return getPrimaryRangeForEndpointWithinDC(keyspace, getBroadcastAddressAndPort());
    }

    @Deprecated(since = "CEP-21")
    public Collection<Range<Token>> getLocalPrimaryRangeForEndpoint(InetAddressAndPort referenceEndpoint)
    {
        ClusterMetadata metadata = ClusterMetadata.current();
        NodeId node = metadata.directory.peerId(referenceEndpoint);
        if (node == null)
            throw new IllegalArgumentException("Unknown endpoint " + referenceEndpoint);
        return SizeEstimatesRecorder.getLocalPrimaryRange(metadata, node);
    }

    @Deprecated(since = "CEP-21")
    public Collection<Range<Token>> getPrimaryRangeForEndpointWithinDC(String keyspace, InetAddressAndPort endpoint)
    {
        return TokenRingUtils.getPrimaryRangeForEndpointWithinDC(keyspace, endpoint);
    }

    @Deprecated(since = "CEP-21")
    public static List<Range<Token>> getAllRanges(List<Token> sortedTokens)
    {
        return TokenRingUtils.getAllRanges(sortedTokens);
    }

    private final Set<InetAddressAndPort> replicatingNodes = Sets.newConcurrentHashSet();
    private CassandraDaemon daemon;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Verify the endpoint is a live cluster member: `nodetool status` and ClusterMetadata.directory peer list.
2. Update the caller to use the current node's address/port after replacement or decommission.
3. Use the TCM-native equivalent (SizeEstimatesRecorder.getLocalPrimaryRange with a NodeId from metadata.directory) instead of the deprecated method.
4. Handle null peerId before calling to avoid the throw.

Example fix

// before
Collection<Range<Token>> r = ss.getLocalPrimaryRangeForEndpoint(InetAddressAndPort.getByName("10.0.0.1"));
// after
NodeId node = ClusterMetadata.current().directory.peerId(endpoint);
if (node != null) {
    Collection<Range<Token>> r = SizeEstimatesRecorder.getLocalPrimaryRange(ClusterMetadata.current(), node);
}

NodeId node = ClusterMetadata.current().directory.peerId(endpoint);
if (node == null) throw new IllegalArgumentException("Endpoint not a cluster member: " + endpoint);

boolean isKnownPeer(InetAddressAndPort ep) {
    return ClusterMetadata.current().directory.peerId(ep) != null;
}

catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unknown endpoint")) {
        refreshClusterMembership(); // reload ClusterMetadata / nodetool status
        return;
    }
    throw e;
}

When it happens

Trigger: Calling StorageService.getLocalPrimaryRangeForEndpoint(InetAddressAndPort) via JMX/programmatic API with an address that is not a registered peer: wrong IP/port, decommissioned node, or a node not yet joined.

Common situations: Monitoring/estimation scripts hard-coding an old node IP after replacement; calling with the local address on a node whose identity registration changed after a CEP-21 (TCM) upgrade; typo in endpoint port.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Disabling compaction by setting min_compaction_threshold or
• %s is not a valid JMX resource name
• JAAS login configuration missing for JMX authenticator setup
• Authentication error
• Unrecognized Callback:

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