apache/cassandra · error · UnsupportedOperationException

Not a node id:

Error message

Not a node id: 

What it means

NodeId.fromUUID converts a UUID to a NodeId only when the UUID was generated by fromString/from node-id encoding, i.e. its least significant bits hold a small non-negative int (isValidNodeId). It throws UnsupportedOperationException for any other UUID, such as a random hostId or schema-version UUID.

Solutions

1. Pass the actual TCM node id-derived UUID (one produced by NodeId's own encoding), not a random hostId
2. Check isValidNodeId(uuid) before calling fromUUID and handle false gracefully
3. Use NodeId.fromString(String) when you have the numeric id like "1"
4. Look up the NodeId via the cluster Directory by endpoint/hostId instead of guessing a UUID

Example fix

// before
NodeId id = NodeId.fromUUID(hostId); // random UUID -> throws
// after
NodeId id = NodeId.isValidNodeId(hostId)
    ? NodeId.fromUUID(hostId)
    : metadata.directory.peerId(endpoint);

if (!NodeId.isValidNodeId(uuid)) throw new IllegalArgumentException(uuid + " is not a node id; use the directory lookup instead");

boolean isNodeIdUuid(java.util.UUID u) { return NodeId.isValidNodeId(u); }

try { return NodeId.fromUUID(uuid); } catch (UnsupportedOperationException e) { return resolveFromDirectory(uuid); }

When it happens

Trigger: Calling NodeId.fromUUID(uuid) with a random UUID (e.g. hostId from system.local or a schema version) whose 0x0FFFFFFFFFFFFFFF-masked least significant bits are not a valid positive node id.

Common situations: Confusing a node's hostId with its nodeId in TCM tooling; passing random UUIDs generated by UUID.randomUUID(); mixing gossip-era hostIds into TCM directory lookups.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Addresses differ: !=
• Can only initialize cluster identifier during epoch
• Can't commit transformations when running in gossip mode…
• Can't finish migration, initiator=
• Can't ignore local host

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tcm/membership/NodeId.java:56

    private final int id;

    public NodeId(int id)
    {
        this.id = id;
    }

    public static NodeId fromString(String nodeOrHostId)
    {
        if (nodeOrHostId.length() == UUID.randomUUID().toString().length())
            return NodeId.fromUUID(UUID.fromString(nodeOrHostId));
        return new NodeId(Integer.parseInt(nodeOrHostId));
    }

    public static NodeId fromUUID(UUID uuid)
    {
        if (!isValidNodeId(uuid))
            throw new UnsupportedOperationException("Not a node id: " + uuid); // see RemoveTest#testBadHostId

        long id = 0x0FFFFFFFFFFFFFFFL & uuid.getLeastSignificantBits();
        return new NodeId(Ints.checkedCast(id));
    }

    public static boolean isValidNodeId(UUID uuid)
    {
        long id = 0x0FFFFFFFFFFFFFFFL & uuid.getLeastSignificantBits();
        return (uuid.getMostSignificantBits() == NODE_ID_UUID_MAGIC && id < Integer.MAX_VALUE) ||
                (uuid.getMostSignificantBits() == 0 && uuid.getLeastSignificantBits() < Integer.MAX_VALUE); // old check, for existing cluster upgrades, no need upstream
    }

    @Deprecated(since = "CEP-21")
    public UUID toUUID()
    {
        long lsb = 0xC000000000000000L | id;
        return new UUID(NODE_ID_UUID_MAGIC, lsb);
    }

View on GitHub (pinned to 88fd0f6a0e)