influxdata/influxdb · error

field family ID and name don't exist

Error message

field family ID and name don't exist

What it means

Panic from `.expect("field family ID and name don't exist")` after inserting a new `FieldFamilyDefinition` into `self.table.field_families` in the v2 catalog update code. The insert can only fail if a field family with the same id or name already exists, which the transaction logic rules out by construction (fresh id allocation plus the field-family log). Its presence indicates catalog state inconsistency.

Solutions

1. Ensure the field family creation op is not duplicated in the catalog log/batch being applied.
2. Check that user-supplied field family names are checked for existence before creating a new family.
3. Restore the catalog from a snapshot taken before the duplicate write.
4. Report to influxdb3 maintainers with the failing batch if reached via supported APIs.

Example fix

// before
self.table.field_families.insert(id, Arc::new(def)).expect("field family ID and name don't exist");
// after
if self.table.field_families.contains_key(&id) {
    return Err(Error::DuplicateFieldFamily { table: self.table.name.clone(), id });
}
self.table.field_families.insert(id, Arc::new(def)).expect("field family ID and name don't exist");

// Check family name/id uniqueness before creating
if table_def.field_families.values().any(|f| f.name == requested_name) {
    return existing_family_id; // reuse instead of creating
}

fn family_exists(table: &TableDefinition, name: &str) -> bool {
    table.field_families.values().any(|f| f.name.to_string() == name)
}

When it happens

Trigger: Creating/adding a field family whose generated id or `FieldFamilyName::User(name)` already exists in `table.field_families` — e.g. replaying a create-field-family op twice, or two user field families sharing the same name due to corrupted log entries.

Common situations: Catalog WAL replay after crash where the same op is applied twice; user-specified family name colliding with an existing one when the pre-check was skipped in a custom/bypass code path; merged or hand-edited catalog files.

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
• field does not exist
• field family name exists
• no duplicate tag
• column id in series key should be valid

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

Appendix: source

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

                if let Some(ffd) = self.table.field_families.get_by_name(family_name) {
                    if ffd.fields.len() >= NUM_FIELDS_PER_FAMILY_LIMIT {
                        return Err(CatalogError::TooManyFields {
                            field_family: family_name.to_string(),
                            limit: NUM_FIELDS_PER_FAMILY_LIMIT,
                        });
                    }
                    ffd.id
                } else {
                    self.check_field_family_limit()?;
                    // create a new field family
                    let id = self.table.field_families.get_and_increment_next_id();
                    let name = FieldFamilyName::User(family_name.into());
                    let def = FieldFamilyDefinition::new(id, name.clone());

                    self.table
                        .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

View on GitHub (pinned to 06200ef96b)