influxdata/influxdb · error · CatalogError

table ' ' is not defined in database ' ', which uses…

Error message

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

What it means

CatalogError::UndeclaredTable is thrown on writes to a database configured with an explicit schema when the target table does not exist in the catalog. In explicit-schema mode the catalog will not auto-create tables, so writes to unknown tables are rejected with instructions to create the table via the /api/v3/configure/table API first.

Solutions

1. Create the table first via POST /api/v3/configure/table with its full column list, then retry the write.
2. Fix the measurement name in the writer to match an existing declared table.
3. If auto-creation is desired, switch the database schema mode back to 'auto'.

Example fix

// before
curl -X POST .../write?db=metrics --data-binary 'newtable host=a val=1i'  // UndeclaredTable
// after
curl -X POST .../api/v3/configure/table -d '{"db":"metrics","table":"newtable","columns":[{"name":"host","type":"tag"},{"name":"val","type":"int64"},{"name":"time","type":"timestamp"}]}'
curl -X POST .../write?db=metrics --data-binary 'newtable host=a val=1i'

async function ensureTable(db, table, columns) {
  const tables = await listTables(db);
  if (!tables.includes(table)) {
    await createTable(db, table, columns);
  }
}

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

When it happens

Trigger: Writing line protocol (or using the write API) to database 'db' and measurement 'm' when 'm' has never been declared and the database's schema_mode is 'explicit'.

Common situations: Typos in measurement names in writers; deploying writers before running table-creation migrations; switching a database from auto to explicit schema mode after tables were previously auto-created.

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

• column ' ' ( ) is not defined in table ' ' of database ' '…
• Cannot write
• cannot write to soft-deleted database
• column type mismatch for column
• error in distinct value cache

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:100

    InvalidLastCacheKeyColumnType,

    #[error("plugin trigger is already enabled")]
    TriggerAlreadyEnabled,

    #[error("plugin trigger is already disabled")]
    TriggerAlreadyDisabled,

    #[error("invalid column type for column '{column_name}', expected {expected}, got {got}")]
    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,

View on GitHub (pinned to 06200ef96b)