{"record":{"id":"7e43939b1c3d18b7","repo":"influxdata/influxdb","slug":"update-to-schema-would-exceed-the-field-family-limit-of-0","errorCode":null,"errorMessage":"Update to schema would exceed the field family limit of {0}","messagePattern":"Update to schema would exceed the field family limit of (.+?)","errorType":"validation","errorClass":"CatalogError","httpStatus":400,"severity":"error","filePath":"influxdb3_catalog/src/error.rs","lineNumber":163,"sourceCode":"        table_name: TruncatedTableName,\n        attempted: usize,\n        limit: usize,\n    },\n\n    #[error(\n        \"Update to schema would exceed number of tables limit: attempted to create table but already have {current} table(s) (limit: {limit})\"\n    )]\n    TooManyTables { current: usize, limit: usize },\n\n    #[error(\"Adding a new database would exceed limit of {0} databases\")]\n    TooManyDbs(usize),\n\n    #[error(\n        \"Update to schema would exceed the field limit ({limit}) for field family '{field_family}'\"\n    )]\n    TooManyFields { field_family: String, limit: usize },\n\n    #[error(\"Update to schema would exceed the field family limit of {0}\")]\n    TooManyFieldFamilies(usize),\n\n    #[error(\n        \"table '{table_name}' in storage mode {storage_mode:?} cannot allocate more legacy column IDs\"\n    )]\n    LegacyColumnIdsExhausted {\n        table_name: Arc<str>,\n        storage_mode: StorageMode,\n    },\n\n    #[error(\"Database not found {}\", db_name)]\n    DatabaseNotFound { db_name: Arc<str> },\n\n    #[error(\"Table {} not in DB schema for {}\", table_name, db_name)]\n    TableNotFound {\n        db_name: Arc<str>,\n        table_name: Arc<str>,\n    },","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/error.rs#L145-L181","documentation":"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.","triggerScenarios":"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.","commonSituations":"Very wide, heterogeneous tables mixing many unrelated schemas into one measurement; long-lived tables that accumulated many disjoint field groups over time.","solutions":["Split the table into multiple purpose-specific tables","Consolidate overlapping fields so existing families suffice","Create a new table for the new schema and migrate/federate queries","Raise the field-family limit in server configuration"],"exampleFix":"// before: catch-all measurement 'events' accumulating unrelated schemas\nevents http_status=200,db_query_ms=3,gps_lat=..,...\n// after: split by domain\nhttp_events status=200\ndb_events query_ms=3\ngeo_events lat=..,lon=..","handlingStrategy":"validation","validationCode":"const FAMILY_LIMIT = 8; // instance-configured\nif (Object.keys(schema.fieldFamilies).length >= FAMILY_LIMIT && requiresNewFamily(newFields, schema)) {\n  throw new Error(`field family limit ${FAMILY_LIMIT} reached`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep each measurement's fields homogeneous; split heterogeneous payloads into separate tables","Watch for gradual schema accretion in long-lived tables","Re-evaluate table design when adding a group of unrelated fields"],"tags":["schema","field-family","catalog","time-series"],"backgroundTag":"value-out-of-range","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"}