{"record":{"id":"8ede22054778d31d","repo":"influxdata/influxdb","slug":"column-column-name-column-type-is-not-defined-in-table-table","errorCode":null,"errorMessage":"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","messagePattern":"column '(.+?)' \\((.+?)\\) is not defined in table '(.+?)' of database '(.+?)', which uses explicit schemas; add the column with the /api/v3/configure/table API before writing to it","errorType":"validation","errorClass":"CatalogError","httpStatus":404,"severity":"error","filePath":"influxdb3_catalog/src/error.rs","lineNumber":109,"sourceCode":"    InvalidColumnType {\n        column_name: Arc<str>,\n        expected: InfluxColumnType,\n        got: InfluxColumnType,\n    },\n\n    #[error(\"'{0}' is a reserved column\")]\n    ReservedColumn(Arc<str>),\n\n    #[error(\n        \"table '{table_name}' is not defined in database '{db_name}', which uses explicit schemas; \\\n         create the table with the /api/v3/configure/table API before writing to it\"\n    )]\n    UndeclaredTable {\n        db_name: Arc<str>,\n        table_name: Arc<str>,\n    },\n\n    #[error(\n        \"column '{column_name}' ({column_type}) is not defined in table '{table_name}' of \\\n         database '{db_name}', which uses explicit schemas; add the column with the \\\n         /api/v3/configure/table API before writing to it\"\n    )]\n    UndeclaredColumn {\n        db_name: Arc<str>,\n        table_name: Arc<str>,\n        column_name: Arc<str>,\n        column_type: InfluxColumnType,\n    },\n\n    #[error(\"invalid node registration\")]\n    InvalidNodeRegistration,\n\n    #[error(\"invalid node name ({0})\")]\n    InvalidNodeName(String),\n\n    #[error(\"invalid node spec: {0}\")]","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/error.rs#L91-L127","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Add the column first via POST /api/v3/configure/table with the add-columns payload, then retry the write.","Remove the undeclared column from the write payload if it is not needed.","Audit writer payloads against the declared table schema and keep them in sync in CI."],"exampleFix":"// before\ncurl -X POST .../write?db=metrics --data-binary 'cpu host=a,region=us val=1i'  // region undeclared\n// after\ncurl -X POST .../api/v3/configure/table -d '{\"db\":\"metrics\",\"table\":\"cpu\",\"add_columns\":[{\"name\":\"region\",\"type\":\"tag\"}]}'\ncurl -X POST .../write?db=metrics --data-binary 'cpu host=a,region=us val=1i'","handlingStrategy":"validation","validationCode":"async function assertColumnsDeclared(db, table, columnsInPayload) {\n  const schema = await getTableSchema(db, table);\n  const known = new Set(schema.columns.map(c => c.name));\n  const missing = columnsInPayload.filter(c => !known.has(c.name));\n  if (missing.length) await addColumns(db, table, missing);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await writeLineProtocol(lines);\n} catch (e) {\n  if (e.message.includes(\"is not defined in table\")) {\n    await addColumnsFromError(db, table, e.message);\n    await writeLineProtocol(lines); // retry once\n  } else { throw e; }\n}","preventionTips":["Keep writer payload schemas and table definitions in one source of truth.","Add columns via /api/v3/configure/table as part of the same PR that changes writers.","Test writers against a database in explicit schema mode."],"tags":["influxdb3","explicit-schema","write","column"],"backgroundTag":"entity-not-found","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}