influxdata/influxdb · error

field family name exists

Error message

field family name exists

What it means

Panic from `.expect("field family name exists")` on `self.table.field_families.get_mut_by_id(&ff_id)` while adding a field column in the v2 catalog update path. Unlike the other expects, this one is a lookup: it fires when the field family id given to add_field_column is NOT present in the table. The caller (or the preceding auto-family allocation step) is expected to have guaranteed the family exists.

Solutions

1. Verify the ff_id comes from an existing family — re-fetch the family id via the table's field_families rather than caching it.
2. Rebuild the table definition from the full catalog log so the field-family definition op is applied before field-add ops.
3. Restore the catalog from a consistent snapshot.
4. If triggered by the auto field family path, check that auto_field_family always points to a valid family id.

Example fix

// before
let ffd_arc = self.table.field_families.get_mut_by_id(&ff_id).expect("field family name exists");
// after
let ffd_arc = self.table.field_families.get_mut_by_id(&ff_id)
    .ok_or_else(|| Error::FieldFamilyNotFound { table: self.table.name.clone(), id: ff_id })?;

// Confirm the family id is live before adding a field to it
if table_def.field_families.get_by_id(&ff_id).is_none() {
    return Err("field family missing; re-fetch id from table definition");
}

fn family_is_present(table: &TableDefinition, id: &FieldFamilyId) -> bool {
    table.field_families.get_by_id(id).is_some()
}

When it happens

Trigger: Calling add_field_column with an ff_id that was never inserted into `table.field_families`, or referencing a field family that was dropped/renamed between allocating the id and using it; also possible if the auto-field-family id points at a family missing from the map.

Common situations: Partially applied catalog batches where the family definition op failed but field-add ops remain; catalogs restored from snapshots where field_families were not fully loaded; custom code passing stale family ids.

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

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

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

Appendix: source

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

                        .field_families
                        .insert(id, Arc::new(def))
                        .expect("field family ID and name don't exist");

                    self.field_family_definitions
                        .push(FieldFamilyDefinitionLog { id, name });

                    id
                }
            }
        };

        let col_id = self.next_legacy_column_id()?;
        let field_col = {
            let ffd_arc = self
                .table
                .field_families
                .get_mut_by_id(&ff_id)
                .expect("field family name exists");

            // Use `Arc::make_mut` because `TableTransaction`s are created via cloning
            // `TableDefinition`s.
            let ffd = Arc::make_mut(ffd_arc);
            let id = FieldIdentifier::new(ffd.id, ffd.fields.get_and_increment_next_id());
            let field_col = Arc::new(FieldColumn::new(id, col_id, name.as_ref(), data_type));
            ffd.fields
                .insert(id.1, Arc::clone(&field_col))
                .expect("field does not exist");
            field_col
        };
        self.table.field_count += 1;

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

View on GitHub (pinned to 06200ef96b)