influxdata/influxdb · error · CatalogError

invalid node spec

Error message

invalid node spec: {0}

What it means

CatalogError::InvalidNodeSpec wraps an anyhow::Error produced when parsing or validating a node spec (the node's configuration/definition) fails. Because the underlying source is preserved via #[source], the wrapped message explains exactly which part of the spec was rejected.

Solutions

1. Read the chained #[source] error message to find the exact spec field that failed and fix that value.
2. Validate the node spec against the current version's expected format before applying it (upgrade tooling if the format changed).
3. Regenerate the spec from a known-good template or via the CLI instead of hand-editing.

Example fix

// before
let spec: NodeSpec = toml::from_str(&raw)?; // InvalidNodeSpec: missing field `mode`
// after
let spec: NodeSpec = toml::from_str(&raw)?; // ensure raw contains: mode = "all"
assert!(raw.contains("mode"), "node spec must include mode");

function validateNodeSpec(spec) {
  const required = ["node_id", "instance_id", "mode"];
  const missing = required.filter(k => spec[k] == null);
  if (missing.length) throw new Error(`node spec missing: ${missing.join(",")}`);
}

const isNodeSpec = (v) => v != null && typeof v === "object"
  && typeof v.node_id === "string" && typeof v.mode === "string";

try {
  catalog.apply_node_spec(&raw_spec)?;
} catch (e) {
  if (e.message.startsWith("invalid node spec")) {
    log.error("node spec rejected:", e.cause ?? e.message); // inspect #[source]
  } else { throw e; }
}

When it happens

Trigger: Loading or parsing a node spec (e.g. from config or catalog) whose content fails validation — malformed spec format, missing required fields, or semantically invalid values.

Common situations: Hand-edited node configuration files with typos; version upgrades where the spec format changed and old specs are re-ingested; environment-driven configuration producing partially-populated specs.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• invalid node name ( )
• invalid node registration
• ' ' is a reserved column
• is not a valid data type, values are int64, uint64…
• auto field family exists

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:127

    #[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,
    },

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

View on GitHub (pinned to 06200ef96b)