What causes "node id ({}) has to be one of cluster member({:?})" in databendlabs/databend?

Set --id to one of the cluster member ids listed in the error message (the keys of the nodes map)

node id ( ) has to be one of cluster member( )

Error message

node id ({}) has to be one of cluster member({:?})

What it means

After building the cluster nodes for a metasrv import, metactl verifies that the node id being imported (from --id) is present among the constructed cluster member node ids. If the id is not a key in the nodes map, the import is aborted because the restored data would not correspond to any known raft member.

Solutions

Set --id to one of the cluster member ids listed in the error message (the keys of the nodes map)
Update the peer/address list so it includes an entry for the node id you are importing
If the cluster changed, regenerate the nodes configuration for the new topology before importing
Double-check whether you intended to import into a 'new cluster' (which skips this check) versus the existing cluster

Example fix

// before
metactl --db --import --id 1 --raft-addr '2,node-2:9191'
// after
metactl --db --import --id 2 --raft-addr '2,node-2:9191'

Defensive patterns

Strategy: validation

Validate before calling

// before import, confirm the --id is present in the cluster member list
const node_ids: Vec<u64> = parse_peer_ids(cluster_peers); // e.g. ['2,node-2:9191'] -> [2]
if !node_ids.contains(&import_id) {
    panic!("--id {} must be one of cluster members {:?}", import_id, node_ids);
}

Prevention

Keep node id and peer list in a single source of truth
After cluster topology changes, regenerate import scripts
Distinguish node id from cluster id in your runbooks
Dry-run the import command and read the printed 'new cluster: {:?}' line to confirm ids

When it happens

Trigger: Running `metactl --db --import` with an --id value that does not match any node id in the --raft-addr/--peers list; e.g. importing a snapshot with node id 1 into a cluster whose declared node id is 2.

Common situations: Cluster reconfiguration after node replacement, reusing an old import command after cluster ids changed, or mixing up node-id with cluster-id.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of databendlabs/databend@288d84d76e (2026-09-11). Data as JSON: /api/errors/cc1057c8ac883cb4. Report an issue: GitHub.

Appendix: source

Thrown at src/meta/control/src/import.rs:186

            _ => {
                return Err(anyhow::anyhow!("invalid peer raft addr: {}", addrs[0]));
            }
        };

        let node = Node::new(id, endpoint.clone());
        eprintln!("new cluster node:{}", node);

        nodes.insert(id, node);
    }

    if nodes.is_empty() {
        return Ok(nodes);
    }

    eprintln!("new cluster: {:?}", nodes);

    if !nodes.contains_key(&id) {
        return Err(anyhow::anyhow!(
            "node id ({}) has to be one of cluster member({:?})",
            id,
            nodes.keys().collect::<Vec<_>>()
        ));
    }

    Ok(nodes)
}

// initial_cluster format: node_id=endpoint,grpc_api_addr;
async fn init_new_cluster<SP: SpawnApi>(
    args: &ImportArgs,
    nodes: BTreeMap<NodeId, Node>,
    max_log_id: Option<LogId>,
) -> anyhow::Result<()> {
    eprintln!();
    eprintln!("Initialize Cluster with: {:?}", nodes);

View on GitHub (pinned to 288d84d76e)