influxdata/influxdb · error · CatalogError

Update to schema would exceed the field limit

Error message

Update to schema would exceed the field limit ({limit}) for field family '{field_family}'

What it means

Thrown when a schema update would exceed the field limit for a specific field family. InfluxDB 3 groups columns into field families; each family has a maximum number of fields, and updates pushing a family past `limit` are rejected. This bounds row width per column group.

Solutions

1. Split fields across a new field family (different write pattern) or a new table
2. Move rarely-queried fields into a compacted representation (e.g. a JSON payload field)
3. Drop unused fields where supported and archive historical data
4. Raise the field-family limit in server configuration

Example fix

// before: one measurement, 300+ fields in one family
machine a1=..,a2=..,...,a300=..
// after: split into logical tables
machine_core rpm=..,temp=..
machine_vib axis_x=..,axis_y=..

const FIELD_FAMILY_LIMIT = 200; // instance-configured
const familyFields = schema.fieldFamilies[family] ?? [];
if (familyFields.length + incomingFields.length > FIELD_FAMILY_LIMIT) {
  throw new Error(`field family '${family}' would exceed ${FIELD_FAMILY_LIMIT} fields`);
}

When it happens

Trigger: Adding fields to a table whose field family for those columns already holds `limit` fields — typically via line-protocol writes introducing new field keys or via ALTER/CREATE adding columns to an existing family.

Common situations: Wide IoT payloads with hundreds of sensor channels; exporters sending every metric as a separate field of one measurement; gradually accumulating field keys over months until the family is full.

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
• Schema update for table
• Update to schema would exceed the field family limit of
• 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/5989dcda9e6d405a. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:158

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

    #[error(
        "Update to schema would exceed number of tables limit: attempted to create table but already have {current} table(s) (limit: {limit})"
    )]
    TooManyTables { current: usize, limit: usize },

    #[error("Adding a new database would exceed limit of {0} databases")]
    TooManyDbs(usize),

    #[error(
        "Update to schema would exceed the field limit ({limit}) for field family '{field_family}'"
    )]
    TooManyFields { field_family: String, limit: usize },

    #[error("Update to schema would exceed the field family limit of {0}")]
    TooManyFieldFamilies(usize),

    #[error(
        "table '{table_name}' in storage mode {storage_mode:?} cannot allocate more legacy column IDs"
    )]
    LegacyColumnIdsExhausted {
        table_name: Arc<str>,
        storage_mode: StorageMode,
    },

    #[error("Database not found {}", db_name)]
    DatabaseNotFound { db_name: Arc<str> },

View on GitHub (pinned to 06200ef96b)