apache/cassandra · error · RuntimeException

Unknown endpoint

Error message

Unknown endpoint 

What it means

Thrown by StorageService.getNativeAddress (used for rpc address lookups) when the given endpoint has no NodeId in cluster metadata's directory - the endpoint is not a known peer. Thrown as RuntimeException since it typically comes from internal address mapping rather than direct user input.

Source

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

        }
        return map;
    }

    /**
     * Return the native address associated with an endpoint as a string.
     * @param endpoint The endpoint to get rpc address for
     * @return the native address
     */
    public String getNativeaddress(InetAddressAndPort endpoint, boolean withPort)
    {
        if (endpoint.equals(getBroadcastAddressAndPort()))
            return FBUtilities.getBroadcastNativeAddressAndPort().getHostAddress(withPort);

        ClusterMetadata metadata = ClusterMetadata.current();
        Directory directory = metadata.directory;
        NodeId id = directory.peerId(endpoint);
        if (id == null)
            throw new RuntimeException("Unknown endpoint " + endpoint);

        NodeAddresses addresses = directory.getNodeAddresses(id);
        return addresses.nativeAddress.getHostAddress(withPort);
    }

    public Map<List<String>, List<String>> getRangeToRpcaddressMap(String keyspace)
    {
        return getRangeToNativeaddressMap(keyspace, false);
    }

    public Map<List<String>, List<String>> getRangeToNativeaddressWithPortMap(String keyspace)
    {
        return getRangeToNativeaddressMap(keyspace, true);
    }

    /**
     * for a keyspace, return the ranges and corresponding RPC addresses for a given keyspace.
     * @param keyspace

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use an endpoint that is a current cluster member (see `nodetool status`)
2. Refresh tooling/monitoring configuration to drop removed node addresses
3. If a node was just removed, wait for cluster metadata convergence and retry
4. For rpc address of arbitrary hosts, configure broadcast/rpc_address correctly on the nodes instead of resolving unknown endpoints

Example fix

// before
// lookup nativeAddress for 10.0.0.9 (removed node)
// after
// read current members from nodetool status and look up only those endpoints

try {
    String nativeAddr = ssProxy.getNativeAddress(endpoint);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unknown endpoint"))
        log.warn("Endpoint {} is not a current cluster member; refresh member list", endpoint);
    else throw e;
}

When it happens

Trigger: Querying the native (rpc) address for an endpoint via JMX/StorageService that is not in cluster metadata; stale client or tooling caches referencing removed nodes; lookup during topology changes before metadata converges.

Common situations: Monitoring scripts using an old node address after decommission/removenode; race between node removal and metadata propagation; misconfigured tooling pointing at a load balancer or VIP instead of a real node.

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

• Can not remove a node that has an in-progress sequence
• This cluster is migrating to cluster metadata, can't move un
• Can not commit transformation: "%s"(%s).
• %s is not a valid JMX resource name
• JAAS login configuration missing for JMX authenticator setup

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