apache/cassandra · error · IllegalArgumentException

No node present with ip address ${ip} in given cluster metad

Error message

No node present with ip address ${ip} in given cluster metadata.

What it means

Thrown by CMSOfflineTool.getNodeId when an IP address is supplied but metadata.directory.peerId(nodeAddress) returns null, i.e. the address is not a known peer in the offline cluster metadata. It guards address-based node resolution before any mutation of the metadata.

Source

Thrown at src/java/org/apache/cassandra/tools/CMSOfflineTool.java:581

        {
            if (id != null)
            {
                NodeId nodeId = NodeId.fromString(id);
                if (!metadata.directory.peerIds().contains(nodeId))
                {
                    throw new IllegalArgumentException("No node present with id " + id +
                                                       " in the given cluster metadata.");
                }
                return nodeId;
            }
            else if (ip != null)
            {
                InetAddressAndPort nodeAddress = InetAddressAndPort.getByNameUnchecked(ip);
                NodeId nodeId = metadata.directory.peerId(nodeAddress);

                if (null == nodeId)
                {
                    throw new IllegalArgumentException("No node present with ip address " + ip +
                                                       " in given cluster metadata.");
                }
                return nodeId;
            }

            throw new IllegalArgumentException("Neither node id nor ip address specified to fetch NodeId from metadata.");
        }
    }


    /**
     * Prints a high-level summary of the CMS state: members, epoch, replication factor,
     * service state, and whether reconfiguration is needed.
     */
    @Command(name = "describe", description = "Describes the cluster metadata.")
    static class Describe extends ClusterMetadataToolCmd
    {
        @Override

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Use the exact host:port pair the node registers under, including the storage port.
Inspect metadata.directory.peerIds()/addresses to confirm the peer exists in this snapshot.
Fall back to the node's NodeId if the IP is uncertain.
Re-capture the cluster metadata if the node joined after the snapshot was taken.

Example fix

// before
// cms offline --ip 10.0.0.5        (no port)
// after
// cms offline --ip 10.0.0.5:7000   (exact peer address:port)

Defensive patterns

Strategy: validation

Validate before calling

InetAddressAndPort addr = InetAddressAndPort.getByNameUnchecked(ip);
if (metadata.directory.peerId(addr) == null)
    throw new IllegalArgumentException("Address " + ip + " is not a peer in this metadata");

Try / catch

try { NodeId id = tool.getNodeId(opts); ... } catch (IllegalArgumentException e) { logger.error("Peer lookup failed: " + e.getMessage()); }

Prevention

Include the storage port in the address
Verify peers exist in the snapshot before running mutations
Prefer node ids over IPs when in doubt

When it happens

Trigger: Passing --ip with an address that is not registered as a peer in the parsed ClusterMetadata: wrong IP/port (InetAddressAndPort includes the port), node not yet a peer at snapshot time, or decommissioned node.

Common situations: Node IP changed after the metadata was captured; port mismatch (tool expects the exact storage port of the peer, e.g. 7000 vs 7001 for TLS); querying a metadata snapshot from a different cluster.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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