influxdata/influxdb · error · CatalogError

node ' ' cannot clear its connection address (conn info…

Error message

node '{node_id}' cannot clear its connection address (conn info e.g. 8181) while it is a member of query group '{query_group_name}' (id {query_group_id})

What it means

This error is raised when a node attempts to clear/remove its advertised connection address (conn info such as port 8181) while it is still a member of a query group. Because query group peers rely on that address to reach the node, the catalog forbids clearing it until the node leaves the group.

Solutions

Remove the node from its query group first, then clear the connection address
Update the connection address to a new value instead of clearing it
If the group is being decommissioned, dissolve the query group, then clear conn info

Example fix

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

Defensive patterns

Strategy: try-catch

Validate before calling

if catalog.query_group_for_node(node_id).is_some() {
    // leave the group before clearing conn info
}

Try / catch

match catalog.clear_node_conn_info(node_id) {
    Err(CatalogError::NodeConnInfoRequiredInQueryGroup { query_group_id, .. }) => {
        catalog.remove_node_from_query_group(query_group_id, node_id)?;
        catalog.clear_node_conn_info(node_id)?;
    }
    r => r?,
}

Prevention

Drain query-group membership before reconfiguring node addresses
Update conn info in place rather than clearing it when possible
Document conn-info dependencies in cluster reconfiguration runbooks

When it happens

Trigger: Calling the catalog API to clear a node's connection info while the node's id is present in a query group's member list (query_group_name/query_group_id in the error).

Common situations: Operators resetting node connection settings during reconfiguration without draining the node from its query group; automation that wipes conn info as part of re-provisioning.

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:394

        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(
        "node '{node_id}' advertises no connection address (conn info e.g. 8181), so other query group members cannot reach it"
    )]
    QueryGroupMemberNotConnectable { node_id: Arc<str> },

    #[error(
        "node '{node_id}' cannot clear its connection address (conn info e.g. 8181) while it is a member of query group '{query_group_name}' (id {query_group_id})"
    )]
    NodeConnInfoRequiredInQueryGroup {
        node_id: Arc<str>,
        query_group_name: Arc<str>,
        query_group_id: QueryGroupId,
    },
}

impl CatalogError {
    pub fn invalid_configuration(message: impl AsRef<str>) -> Self {
        Self::InvalidConfiguration {
            message: Box::from(message.as_ref()),
        }
    }

    pub fn unexpected(message: impl Into<String>) -> Self {
        Self::Other(anyhow!(message.into()))

View on GitHub (pinned to 06200ef96b)