influxdata/influxdb · error

auto field family exists

Error message

auto field family exists

What it means

Panic from `.expect("auto field family exists")` on `self.table.field_families.get_by_id(id)` inside the auto-field-family allocation logic of the v2 catalog update path. `table.auto_field_family` is an Option<id> that must always reference a family present in `field_families`; firing means the pointer is dangling and the table definition is inconsistent.

Solutions

1. Rebuild the table definition from the complete catalog log so the auto family's definition op is reapplied.
2. Clear or reset `table.auto_field_family` when the referenced family is missing (repair the pointer).
3. Restore the catalog from a consistent backup.
4. Report the inconsistency upstream with the affected catalog file/batch.

Example fix

// before
let ffd = self.table.field_families.get_by_id(id).expect("auto field family exists");
// after
let ffd = match self.table.field_families.get_by_id(id) {
    Some(ffd) => ffd,
    None => { self.table.auto_field_family = None; return self.create_new_auto_field_family(); }
};

// Before using the auto family, verify the pointer is live
let ok = table_def.auto_field_family
    .map(|id| table_def.field_families.get_by_id(&id).is_some())
    .unwrap_or(true);

fn auto_family_is_valid(table: &TableDefinition) -> bool {
    table.auto_field_family.as_ref()
        .map(|id| table.field_families.get_by_id(id).is_some())
        .unwrap_or(true)
}

When it happens

Trigger: Adding a field when `auto_field_family` is Some(id) but no family with that id exists in `table.field_families` — e.g. the family was removed without clearing auto_field_family, or the definition op was dropped during partial replay/restore.

Common situations: Catalog snapshots restored where field family definitions were pruned but the table's auto pointer remained; hand-edited catalogs; bugs in family deletion logic; WAL replay out of order.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• field family ID and name don't exist
• field family name exists
• column id in series key should be valid
• database should exist by id
• field does not exist

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

Appendix: source

Thrown at influxdb3_catalog/src/catalog/versions/v2/update.rs:1767

        let col_def = ColumnDefinition::Field(Arc::clone(&field_col));
        self.table
            .columns
            .insert(col_def.clone())
            .expect("no duplicate column");

        self.column_definitions.push(col_def.into());

        Ok(field_col)
    }

    fn next_auto_family_id(&mut self) -> Result<FieldFamilyId> {
        // Check if the current field family still has available slots.
        if let Some(id) = self.table.auto_field_family.as_ref() {
            let ffd = self
                .table
                .field_families
                .get_by_id(id)
                .expect("auto field family exists");

            if ffd.fields.len() < NUM_FIELDS_PER_FAMILY_LIMIT {
                return Ok(*id);
            }
        }

        self.check_field_family_limit()?;
        let id = self.table.field_families.get_and_increment_next_id();
        self.table.auto_field_family = Some(id);
        let auto_id = self.table.next_auto_field_family_name;
        self.table.next_auto_field_family_name = auto_id + 1;
        let name = FieldFamilyName::Auto(auto_id);

        let def = FieldFamilyDefinition::new(id, name.clone());

        self.table
            .field_families
            .insert(id, Arc::new(def))

View on GitHub (pinned to 06200ef96b)