influxdata/influxdb · error · CatalogError

Schema update for table

Error message

Schema update for table '{table_name}' would exceed the column limit: proposed schema update would have {attempted} columns, but the limit is {limit}

What it means

Thrown by influxdb3_catalog when a schema update would push a table past the maximum allowed number of columns. The catalog enforces a hard column limit per table (default 500-ish, configurable per instance), and any write or DDL that would add columns beyond that limit is rejected atomically. This prevents unbounded column growth from degrading query and write performance.

Solutions

1. Check the table's current column count and remove unused columns, or create a new table with a narrower schema
2. Reduce the variety of field keys in incoming writes (normalize dynamic keys into a fixed set of tags/fields)
3. Split the data across multiple tables or databases
4. Raise the column limit in the server configuration if it was set too low (note performance implications)

Example fix

// before: line protocol with arbitrary field keys per metric
weather,location=us temp=72,humidity=60,pressure=1013,... (hundreds of keys)
// after: fixed schema, dynamic data stored as JSON or a secondary table
weather,location=us temp=72,humidity=60
weather_extra,location=us payload="{\"pressure\":1013}"

const COLUMN_LIMIT = 500; // instance-configured
if (schema.columns.length + newColumns.length > COLUMN_LIMIT) {
  throw new Error(`would exceed column limit (${COLUMN_LIMIT})`);
}

function withinColumnLimit(count: number, limit: number): boolean { return Number.isInteger(count) && count <= limit; }

When it happens

Trigger: Adding new fields (e.g. via a line-protocol write with new tag/field keys) or a DDL CREATE/ALTER that would make the table's column count exceed the configured limit. `attempted` is the resulting column count, `limit` is the max.

Common situations: Writers sending high-cardinality or ever-changing field sets (metrics with dynamic keys); schema drift from many producers; after a limit change, tables already near the cap; migrating data from schemaless systems like MongoDB into InfluxDB.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Schema update for table
• Update to schema would exceed the field family limit of
• Update to schema would exceed the field limit
• cannot add column because it already exists with type
• column id in series key should be valid

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:130

         /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,
        attempted: usize,
        limit: usize,
    },

View on GitHub (pinned to 06200ef96b)