influxdata/influxdb · error · CatalogError

table ' ' in storage mode cannot allocate more legacy…

Error message

table '{table_name}' in storage mode {storage_mode:?} cannot allocate more legacy column IDs

What it means

Thrown when a table in legacy storage mode has exhausted its available legacy column IDs. Legacy mode allocates columns from a fixed-size ID space (u8/u16 era compatibility), so once all IDs are allocated, no new columns can be added to that table and this error is raised.

Solutions

1. Migrate the table to the current (non-legacy) storage mode so columns get fresh IDs
2. Create a new table in the modern storage mode and backfill/migrate data
3. Reduce the table's column count by dropping unused columns
4. Upgrade the instance/replication path so new tables are not created in legacy mode

Example fix

// before: wide table still on legacy storage mode
-- writes to 'metrics' keep failing with LegacyColumnIdsExhausted
CREATE TABLE metrics_v2 (...); -- modern mode, migrate data
INSERT INTO metrics_v2 SELECT * FROM metrics;

const table = await catalog.getTable(db, name);
if (table.storageMode.isLegacy() && table.columnIdUsagePct > 90) {
  // plan migration to modern storage mode before adding columns
}

try {
  await write(points);
} catch (e) {
  if (String(e.message).includes('legacy column IDs')) {
    await migrateTableToModernStorage(table);
  } else throw e;
}

When it happens

Trigger: Any schema update adding columns to a table whose `storage_mode` (reported in the error) is a legacy mode and whose legacy column ID pool is exhausted.

Common situations: Older tables created before the current storage engine's schema handling; instances upgraded from earlier InfluxDB 3 versions where tables remain in legacy mode; very wide legacy tables that slowly grew past the ID space.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• cannot add column because it already exists with type
• column id in series key should be valid
• Field type mismatch on table
• Schema update for table
• Schema update for table

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:166

    },

    #[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(
        "Update to schema would exceed the field limit ({limit}) for field family '{field_family}'"
    )]
    TooManyFields { field_family: String, limit: usize },

    #[error("Update to schema would exceed the field family limit of {0}")]
    TooManyFieldFamilies(usize),

    #[error(
        "table '{table_name}' in storage mode {storage_mode:?} cannot allocate more legacy column IDs"
    )]
    LegacyColumnIdsExhausted {
        table_name: Arc<str>,
        storage_mode: StorageMode,
    },

    #[error("Database not found {}", db_name)]
    DatabaseNotFound { db_name: Arc<str> },

    #[error("Table {} not in DB schema for {}", table_name, db_name)]
    TableNotFound {
        db_name: Arc<str>,
        table_name: Arc<str>,
    },

    #[error(
        "Field type mismatch on table {} column {}. Existing column is {} but attempted to add {}",

View on GitHub (pinned to 06200ef96b)