influxdata/influxdb · error · CatalogError

cannot remove node ' ' because it is a member of query…

Error message

cannot remove node '{node_id}' because it is a member of query group '{query_group_name}' (id {query_group_id})

What it means

This error is returned by the InfluxDB 3 catalog when an attempt is made to remove a node that is currently a member of a query group. The catalog prevents removal because query groups require their member nodes to remain present for distributed query planning; removing a member silently would break the group. The error carries the node id and the name/id of the blocking query group so the operator can act on the group first.

Solutions

Remove the node from its query group first (update the query group membership to exclude node_id), then retry the node removal
Dissolve or reconfigure the query group if it is no longer needed, then remove the node
Verify the node id is correct — a stale/wrong node id may still be referenced by an old query group

Example fix

// before
catalog.remove_node(node_id)?; // fails: node still in query group
// after
catalog.remove_node_from_query_group(query_group_id, node_id)?;
catalog.remove_node(node_id)?;

Defensive patterns

Strategy: try-catch

Validate before calling

let is_member = catalog.query_groups().iter()
    .any(|g| g.member_node_ids().contains(&node_id));
if is_member { /* remove from group first */ }

Try / catch

match catalog.remove_node(node_id) {
    Err(e @ CatalogError::NodeInQueryGroup { query_group_id, .. }) => {
        catalog.remove_node_from_query_group(query_group_id, node_id)?;
        catalog.remove_node(node_id)?;
    }
    r => r?,
}

Prevention

Before deleting a node, always query its query-group membership
Build node decommission runbooks that drain query groups first
Check catalog state before scripted bulk node cleanup

When it happens

Trigger: Calling the catalog API to delete/remove a node (e.g. node removal via admin/catalog APIs) while that node's id still appears in a query group's member list.

Common situations: Operators decommissioning or replacing a cluster node without first draining it from its query group; scripted node cleanup after a failed upgrade; attempting `influxdb3` node removal while the node is still registered in query-group membership in the catalog.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/e5d96f3d65247346. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:371

        committed: FeatureLevel,
    },

    #[error(
        "this node's feature level (core={}, enterprise={}) is below the cluster's committed level (core={}, enterprise={}); upgrade required",
        local.core,
        local.enterprise,
        committed.core,
        committed.enterprise,
    )]
    NodeBelowCommittedFeatureLevel {
        committed: FeatureLevel,
        local: FeatureLevel,
    },

    #[error("missing object store for restore operation")]
    MissingObjectStoreForRestore,

    #[error(
        "cannot remove node '{node_id}' because it is a member of query group '{query_group_name}' (id {query_group_id})"
    )]
    NodeInQueryGroup {
        node_id: Arc<str>,
        query_group_name: Arc<str>,
        query_group_id: QueryGroupId,
    },

    #[error(
        "cannot place node '{node_id}' in this query group because it already belongs to query group '{query_group_name}' (id {query_group_id})"
    )]
    NodeAlreadyInQueryGroup {
        node_id: Arc<str>,
        query_group_name: Arc<str>,
        query_group_id: QueryGroupId,
    },

    #[error(

View on GitHub (pinned to 06200ef96b)