influxdata/influxdb · error · CatalogError

Update to schema would exceed the field family limit of

Error message

Update to schema would exceed the field family limit of {0}

What it means

Thrown when creating a new field family would exceed the configured maximum number of field families. InfluxDB 3 partitions a table's fields into families; once the table already has the maximum, schema updates requiring a new family are rejected with this error.

Solutions

1. Split the table into multiple purpose-specific tables
2. Consolidate overlapping fields so existing families suffice
3. Create a new table for the new schema and migrate/federate queries
4. Raise the field-family limit in server configuration

Example fix

// before: catch-all measurement 'events' accumulating unrelated schemas
events http_status=200,db_query_ms=3,gps_lat=..,...
// after: split by domain
http_events status=200
db_events query_ms=3
geo_events lat=..,lon=..

const FAMILY_LIMIT = 8; // instance-configured
if (Object.keys(schema.fieldFamilies).length >= FAMILY_LIMIT && requiresNewFamily(newFields, schema)) {
  throw new Error(`field family limit ${FAMILY_LIMIT} reached`);
}

When it happens

Trigger: A write or DDL that would introduce a new field family (fields that cannot fit existing families) on a table that already has `limit` families.

Common situations: Very wide, heterogeneous tables mixing many unrelated schemas into one measurement; long-lived tables that accumulated many disjoint field groups over time.

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 limit
• auto field family exists
• cannot add column because it already exists with type

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:163

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

    #[error("Table {} not in DB schema for {}", table_name, db_name)]
    TableNotFound {
        db_name: Arc<str>,
        table_name: Arc<str>,
    },

View on GitHub (pinned to 06200ef96b)