apache/cassandra · error · IllegalArgumentException

No node present with id ${id} in the given cluster metadata.

Error message

No node present with id ${id} in the given cluster metadata.

What it means

Thrown by CMSOfflineTool.getNodeId when the node id supplied via CLI options cannot be found in the ClusterMetadata's directory peerIds of an offline cluster metadata file. It validates that the requested NodeId exists before proceeding with offline CMS operations. The metadata was loaded from a file, so only nodes known at snapshot time can be resolved.

Source

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

        private String ip;

        @Option(names = { "-id", "--node-id" }, required = true,
        description = "Node ID. It can be integer ID assigned to node or the node uuid.")
        private String id;

        String getNodeIpOrId()
        {
            return ip != null ? ip : id;
        }

        NodeId getNodeId(ClusterMetadata metadata)
        {
            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.");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. List the valid node ids in the metadata and use one of them (e.g. via the tool's info/summary output or metadata.directory.peerIds()).
  2. Re-export a fresh cluster metadata snapshot if the current one is stale.
  3. If you only know the IP, pass the IP address instead of the id so the peerId(address) lookup is used.
  4. Verify the id string parses to the correct NodeId (format is a numeric id; check for transcription errors).

Example fix

// before
// --id 8f1e...unknown-node-id
// after
// cms offline --id 3  (an id present in metadata.directory.peerIds())
Defensive patterns

Strategy: validation

Validate before calling

NodeId candidate = NodeId.fromString(id);
if (!metadata.directory.peerIds().contains(candidate))
    throw new IllegalArgumentException("Unknown node id " + id + "; valid ids: " + metadata.directory.peerIds());

Try / catch

try { NodeId nodeId = tool.getNodeId(opts); ... } catch (IllegalArgumentException e) { logger.error("Node id not in metadata: " + e.getMessage()); }

Prevention

When it happens

Trigger: Calling the CMSOfflineTool subcommand with --id set to a NodeId that is absent from metadata.directory.peerIds() of the parsed cluster metadata (typo, node never joined, node already removed, or stale metadata file).

Common situations: Typo in the node id on the command line; running the tool against an old/stale cluster metadata snapshot that no longer contains the node; referencing a node that was decommissioned before the metadata was exported.

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/ffa4f3c1e5ecf5fb. Report an issue: GitHub.