influxdata/influxdb · error · CatalogError

invalid unregister for node

Error message

invalid unregister for node '{node_id}' (current state: {current_state})

What it means

Raised when an unregister request for a node is invalid given the node's current lifecycle state in the catalog. Unregistration is only permitted from specific states; requesting it from a running or otherwise ineligible state is rejected. The error carries the node_id and current state to aid diagnosis.

Solutions

1. Stop the node and wait until its catalog state reaches the state required for unregistering, then retry.
2. Check the reported current_state and issue the correct intermediate transition (e.g. stop ack) first.
3. Skip the call if the node is already unregistered (the operation already succeeded).
4. Fix automation ordering so unregister always follows successful stop.

Example fix

// before
catalog.unregister_node(node_id).await?;
// after
let state = catalog.node_state(node_id)?.current_state;
if state != "stopped" {
    return Err(format!("node {node_id} must be stopped first (state: {state})").into());
}
catalog.unregister_node(node_id).await?;

let state = catalog.node_state(node_id)?.current_state;
if !unregister_allowed_states().contains(&state) {
    return Err(format!("node {node_id} in state {state}; cannot unregister"));
}

match result {
    Err(CatalogError::InvalidUnregister { current_state, .. }) => {
        log::warn!("unregister rejected, node state={current_state}");
    }
    other => other?,
}

When it happens

Trigger: Calling the catalog unregister-node API with a node_id whose state machine state does not allow unregistering (e.g. node not yet stopped, or already unregistered).

Common situations: Decommission scripts that unregister before the node finishes stopping; double-unregister from retried automation; operator forgets to stop the node before removing it.

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

• invalid stop ack for node
• node ' ' has compact mode and cannot be removed
• idempotent no-op
• metric should be in progress
• no metric in progress

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:317

    #[error(
        "node '{node_id}' is not fully stopped (current state: {current_state}); run \"stop node\" first"
    )]
    NodeNotFullyStopped {
        node_id: Arc<str>,
        current_state: &'static str,
    },

    #[error("node '{node_id}' has compact mode and cannot be removed")]
    NodeModeNotRemovable { node_id: Arc<str> },

    #[error("invalid stop ack for node '{node_id}' (current state: {current_state})")]
    InvalidStopAck {
        node_id: Arc<str>,
        current_state: &'static str,
    },

    #[error("invalid unregister for node '{node_id}' (current state: {current_state})")]
    InvalidUnregister {
        node_id: Arc<str>,
        current_state: &'static str,
    },

    #[error("idempotent no-op")]
    IdempotentNoOp,

    #[error("cannot delete operator token")]
    CannotDeleteOperatorToken,

    #[error(
        "cannot change the configured generation duration for level {level}; \
        attempted to set to {attempted:#} but its already set to {existing:#}"
    )]
    CannotChangeGenerationDuration {
        level: u8,
        existing: Duration,

View on GitHub (pinned to 06200ef96b)