influxdata/influxdb · error · CatalogError

cannot add column because it already exists with type

Error message

cannot add column {name} because it already exists with type {existing}

What it means

Thrown when a schema update attempts to add a column whose name already exists in the table's schema, and the existing column has a type (reported in the message). Schema evolution in the catalog forbids duplicate column names, even for identical types, via the add-column path.

Solutions

1. Check the table schema for the column before adding; skip or use the existing column.
2. If the write path inferred the wrong type, align your data's field/tag naming with the existing schema.
3. Make migrations idempotent: add the column only when it is absent.
4. If a type conflict is the real issue, plan a new column name rather than reusing the existing one.

Example fix

// before
table_def.add_column("region", InfluxColumnType::Tag)?;
// after
if table_def.column_exists("region") {
    // reuse existing column
} else {
    table_def.add_column("region", InfluxColumnType::Tag)?;
}

if let Some(col) = table_def.column("{name}") {
    // column exists; skip add or reuse it
    return Ok(());
}

fn column_absent(t: &TableDefinition, name: &str) -> bool { t.columns().iter().all(|c| c.name() != name) }

match result {
    Err(CatalogError::DuplicateColumn { name, existing }) => {
        log::debug!("column {name} already exists as {existing:?}; reusing");
    }
    other => other?,
}

When it happens

Trigger: Calling table schema add_columns / the write path with inferred schema when a field or tag name collides with an existing column; re-running a migration that adds a column already added.

Common situations: Line-protocol writes where a new field name matches an existing tag (or vice versa); idempotent schema migrations reapplied; renamed ingestion sources producing colliding field names.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• column id in series key should be valid
• Field type mismatch on table
• Schema update for table
• Schema update for table
• table ' ' in storage mode cannot allocate more legacy…

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:339

    },

    #[error("idempotent no-op")]
    IdempotentNoOp,

    #[error("cannot delete operator token")]
    CannotDeleteOperatorToken,

    #[error(
        "cannot change the configured generation duration for level {level}; \
        attempted to set to {attempted:#} but its already set to {existing:#}"
    )]
    CannotChangeGenerationDuration {
        level: u8,
        existing: Duration,
        attempted: Duration,
    },

    #[error("cannot add column {name} because it already exists with type {existing}")]
    DuplicateColumn {
        name: Arc<str>,
        existing: InfluxColumnType,
    },

    #[error(
        "record id {record_id} exceeds the cluster's committed feature level (core={}, enterprise={}); \
        the cluster must finish upgrading before this operation is available",
        committed.core,
        committed.enterprise,
    )]
    RecordExceedsCommittedFeatureLevel {
        record_id: u16,
        committed: FeatureLevel,
    },

    #[error(
        "this node's feature level (core={}, enterprise={}) is below the cluster's committed level (core={}, enterprise={}); upgrade required",

View on GitHub (pinned to 06200ef96b)