influxdata/influxdb · error · CatalogError

Schema update for table

Error message

Schema update for table '{table_name}' would exceed the tag column limit: proposed schema would have {attempted} tag columns, but the limit is {limit}

What it means

Thrown when a schema update would give a table more tag columns than the catalog allows. Tags are indexed columns, so the limit is lower and stricter than the general column limit. The update is rejected before any data is written.

Solutions

1. Demote non-indexed, high-cardinality attributes from tags to fields
2. Consolidate several tags into a single compound tag (e.g. region-zone) or drop redundant tags
3. Create a new table with a leaner tag schema and migrate data
4. Raise the tag column limit in server configuration if genuinely needed

Example fix

// before: too many tags
cpu,host=h1,region=us,az=1a,dc=dc1,rack=r7,os=linux,arch=amd64 usage=80
// after: fold tags into one or move to fields
cpu,host=h1,env=us-1a usage=80,os="linux",arch="amd64"

const TAG_LIMIT = 200; // instance-configured
const newTags = Object.keys(point.tags);
if (existingTagCount + newTags.length > TAG_LIMIT) {
  throw new Error(`tag limit ${TAG_LIMIT} would be exceeded`);
}

function isTagSet(obj: unknown): obj is Record<string, string> { return typeof obj === 'object' && obj !== null && Object.values(obj).every(v => typeof v === 'string'); }

When it happens

Trigger: A line-protocol write containing more distinct tag keys than allowed on the target table, or DDL that adds tag columns pushing the count over the limit. `attempted` is the resulting tag column count, `limit` the max.

Common situations: Instruments/agents emitting per-host or per-device attributes as tags; users mistaking high-cardinality dimensions for tags; Terraform/telegraf configurations with large tag sets; schemaless migration where every dimension became a tag.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Schema update for table
• Update to schema would exceed the field family limit of
• Update to schema would exceed the field limit
• cannot add column because it already exists with type
• column id in series key should be valid

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:140

    InvalidNodeRegistration,

    #[error("invalid node name ({0})")]
    InvalidNodeName(String),

    #[error("invalid node spec: {0}")]
    InvalidNodeSpec(#[source] anyhow::Error),

    #[error(
        "Schema update for table '{table_name}' would exceed the column limit: \
        proposed schema update would have {attempted} columns, but the limit is {limit}"
    )]
    TooManyColumns {
        table_name: TruncatedTableName,
        attempted: usize,
        limit: usize,
    },

    #[error(
        "Schema update for table '{table_name}' would exceed the tag column limit: \
        proposed schema would have {attempted} tag columns, but the limit is {limit}"
    )]
    TooManyTagColumns {
        table_name: TruncatedTableName,
        attempted: usize,
        limit: usize,
    },

    #[error(
        "Update to schema would exceed number of tables limit: attempted to create table but already have {current} table(s) (limit: {limit})"
    )]
    TooManyTables { current: usize, limit: usize },

    #[error("Adding a new database would exceed limit of {0} databases")]
    TooManyDbs(usize),

    #[error(

View on GitHub (pinned to 06200ef96b)