influxdata/influxdb · error · CatalogError

column ' ' ( ) is not defined in table ' ' of database ' '…

Error message

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

What it means

CatalogError::UndeclaredColumn is thrown on writes to a database with an explicit schema when the payload references a column (tag or field) that is not part of the target table's declared schema. Like UndeclaredTable, the catalog refuses to add the column implicitly and instructs the user to extend the table via the /api/v3/configure/table API. The error names the column and its observed type.

Solutions

1. Add the column first via POST /api/v3/configure/table with the add-columns payload, then retry the write.
2. Remove the undeclared column from the write payload if it is not needed.
3. Audit writer payloads against the declared table schema and keep them in sync in CI.

Example fix

// before
curl -X POST .../write?db=metrics --data-binary 'cpu host=a,region=us val=1i'  // region undeclared
// after
curl -X POST .../api/v3/configure/table -d '{"db":"metrics","table":"cpu","add_columns":[{"name":"region","type":"tag"}]}'
curl -X POST .../write?db=metrics --data-binary 'cpu host=a,region=us val=1i'

async function assertColumnsDeclared(db, table, columnsInPayload) {
  const schema = await getTableSchema(db, table);
  const known = new Set(schema.columns.map(c => c.name));
  const missing = columnsInPayload.filter(c => !known.has(c.name));
  if (missing.length) await addColumns(db, table, missing);
}

try {
  await writeLineProtocol(lines);
} catch (e) {
  if (e.message.includes("is not defined in table")) {
    await addColumnsFromError(db, table, e.message);
    await writeLineProtocol(lines); // retry once
  } else { throw e; }
}

When it happens

Trigger: Writing a line-protocol point containing a tag/field (e.g. 'region') that the table 'cpu' in database 'metrics' has not declared, while the database schema_mode is 'explicit'.

Common situations: Writers gaining new fields before the schema migration runs; tag sets differing per host/region; sending debug/diagnostic fields ad hoc that were never declared.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• table ' ' is not defined in database ' ', which uses…
• ' ' is a reserved column
• Cannot write
• cannot write to soft-deleted database
• column type mismatch for column

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:109

    InvalidColumnType {
        column_name: Arc<str>,
        expected: InfluxColumnType,
        got: InfluxColumnType,
    },

    #[error("'{0}' is a reserved column")]
    ReservedColumn(Arc<str>),

    #[error(
        "table '{table_name}' is not defined in database '{db_name}', which uses explicit schemas; \
         create the table with the /api/v3/configure/table API before writing to it"
    )]
    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}")]

View on GitHub (pinned to 06200ef96b)