influxdata/influxdb · error · CatalogError

invalid node registration

Error message

invalid node registration

What it means

CatalogError::InvalidNodeRegistration is thrown when a node registration request fails the catalog's validation invariants — for example, registering a node whose identity conflicts with an existing registration (such as the same instance ID under a different name or a running node being re-registered with different attributes). Raised from node registration ops (e.g. influxdb3_catalog/src/catalog/versions/v3/ops/node.rs:57).

Solutions

1. Ensure each node has a unique instance ID (regenerate it if the machine/image was cloned).
2. Match the registration attributes (node ID, mode) to the existing registration instead of changing them.
3. Remove/deregister the stale node entry in the catalog before re-registering with new attributes.

Example fix

// before
// cloned node reuses instance_id from image
register_node(instance_id: "abc123", node_id: "node-b")  // InvalidNodeRegistration
// after
let instance_id = Uuid::new_v4().to_string(); // fresh id per node
register_node(instance_id, node_id: "node-b")

function assertFreshInstance(instanceId) {
  const marker = localStorage.getItem("instance_id");
  if (marker && marker !== instanceId) throw new Error("instance id changed; was the node cloned?");
  localStorage.setItem("instance_id", instanceId);
}

try {
  await registerNode(node);
} catch (e) {
  if (e.message === "invalid node registration") {
    await deregisterStaleNode(node.node_id);
    await registerNode(node);
  } else { throw e; }
}

When it happens

Trigger: Calling the node registration API/catalog register_node with a node whose instance ID matches an existing node registered with different attributes (e.g. a different running mode), so the catalog cannot reconcile the registration.

Common situations: Cloning a VM/container image so the new node reuses the old instance ID; re-pointing a node at an existing catalog after a hostname change; running a second influxdb3 instance against a shared catalog with a copied configuration.

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

• auto field family exists
• column id in series key should be valid
• database should exist by id
• field does not exist
• field family ID and name don't exist

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:121

    )]
    UndeclaredTable {
        db_name: Arc<str>,
        table_name: Arc<str>,
    },

    #[error(
        "column '{column_name}' ({column_type}) is not defined in table '{table_name}' of \
         database '{db_name}', which uses explicit schemas; add the column with the \
         /api/v3/configure/table API before writing to it"
    )]
    UndeclaredColumn {
        db_name: Arc<str>,
        table_name: Arc<str>,
        column_name: Arc<str>,
        column_type: InfluxColumnType,
    },

    #[error("invalid node registration")]
    InvalidNodeRegistration,

    #[error("invalid node name ({0})")]
    InvalidNodeName(String),

    #[error("invalid node spec: {0}")]
    InvalidNodeSpec(#[source] anyhow::Error),

    #[error(
        "Schema update for table '{table_name}' would exceed the column limit: \
        proposed schema update would have {attempted} columns, but the limit is {limit}"
    )]
    TooManyColumns {
        table_name: TruncatedTableName,
        attempted: usize,
        limit: usize,
    },

View on GitHub (pinned to 06200ef96b)