influxdata/influxdb · critical · CatalogError

this node's feature level

Error message

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

What it means

Thrown when a node's own supported feature level (core/enterprise pair) is lower than the feature level the cluster has already committed to. The cluster has advanced past what this node's binary understands, so the node must not join or serve until upgraded.

Solutions

Upgrade the node's binary to a version whose feature level is >= the committed level.
Verify image/version configuration so deployments do not roll back to older versions.
If a downgrade is intentional, it is unsupported once the committed level advanced; restore a catalog from before the upgrade instead.
Check core vs enterprise editions match the cluster's committed level.

Example fix

// before
// node starts with old binary against upgraded catalog
// after
let committed = catalog.committed_feature_level();
if local.feature_level() < committed {
    return Err("upgrade node binary before joining cluster".into());
}

Defensive patterns

Strategy: validation

Validate before calling

if local.feature_level() < catalog.committed_feature_level() {
    return Err("node binary too old for committed cluster feature level".into());
}

Try / catch

match result {
    Err(CatalogError::NodeBelowCommittedFeatureLevel { committed, local }) => {
        log::error!("upgrade required: local={local:?} committed={committed:?}");
    }
    other => other?,
}

Prevention

Pin all node images to the same version in deployments
Check feature level at startup before joining
Restore backups only onto same-or-newer installations

When it happens

Trigger: Starting a node with an older binary against a catalog whose committed FeatureLevel is higher; a downgrade followed by reconnect to an upgraded cluster; applying catalog snapshots from newer versions to older nodes.

Common situations: Rolling upgrade where an old replica restarts; Kubernetes rolling deploy misconfigured to run the previous image; restoring a newer catalog backup onto an older installation.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:356

    #[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",
        local.core,
        local.enterprise,
        committed.core,
        committed.enterprise,
    )]
    NodeBelowCommittedFeatureLevel {
        committed: FeatureLevel,
        local: FeatureLevel,
    },

    #[error("missing object store for restore operation")]
    MissingObjectStoreForRestore,

    #[error(
        "cannot remove node '{node_id}' because it is a member of query group '{query_group_name}' (id {query_group_id})"
    )]
    NodeInQueryGroup {

View on GitHub (pinned to 06200ef96b)