influxdata/influxdb · error · CatalogError

only tag and string columns are supported in the distinct…

Error message

only tag and string columns are supported in the distinct cache

What it means

CatalogError::InvalidDistinctCacheColumnType is thrown when a distinct-value cache is configured with a column whose type cannot be cached. Only tag and string columns support distinct-value caching; numeric, boolean, and time columns are rejected. This is a static schema check performed when the cache is created.

Solutions

1. Restrict the cache's columns to tag or string columns in the table
2. Split the cache: use a last-cache for numeric columns instead
3. Check ColumnType of each requested column before creating the cache
4. Drop and recreate the cache with only supported columns

Example fix

// before
DistinctCacheCreate { columns: vec!["value".into()], .. } // value is float
// after
DistinctCacheCreate { columns: vec!["region".into(), "host".into()], .. }

// Rust: only tag/string columns into a distinct cache
let ok = cols.iter().all(|c| matches!(
    table.column(c).map(|c| c.data_type()),
    Some(ColumnDataType::Tag | ColumnDataType::String)
));
assert!(ok, "distinct cache columns must be tag or string");

fn distinct_cacheable(t: ColumnDataType) -> bool {
    matches!(t, ColumnDataType::Tag | ColumnDataType::String)
}

match db.create_distinct_cache(cfg).await {
    Err(CatalogError::InvalidDistinctCacheColumnType) => {
        eprintln!("use only tag/string columns, or a last-cache for numerics");
    }
    other => other?,
}

When it happens

Trigger: POST /api/v3/configure/distinct_cache with columns including an int64/uint64/bool/float/timestamp column; CREATE DISTINCT CACHE SQL referencing a numeric field; auto-configured cache picking up a non-tag/string column.

Common situations: Assuming all columns are cacheable; schema changed from a string to a numeric type after the cache was defined; generating cache configs programmatically without checking column types.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• cannot use a column of type
• must pass a non-empty set of column ids
• All `DataPoints` must have at least one field. Builder…
• At least one field is required
• cache error

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:78

    #[error("no catalog changes to apply: {details}")]
    NoCatalogChange { details: String },

    /// Request is invalid.
    #[error("catalog internal error: {details}")]
    Internal { details: String },

    #[error(
        "persisted catalog checkpoint sequence {checkpoint_sequence} is ahead of live catalog sequence {live_sequence}"
    )]
    BackupCheckpointAhead {
        checkpoint_sequence: u64,
        live_sequence: u64,
    },

    #[error("invalid configuration provided: {message}")]
    InvalidConfiguration { message: Box<str> },

    #[error("only tag and string columns are supported in the distinct cache")]
    InvalidDistinctCacheColumnType,

    #[error("only uint64, int64, bool, tag, and string columns are supported in the last cache")]
    InvalidLastCacheKeyColumnType,

    #[error("plugin trigger is already enabled")]
    TriggerAlreadyEnabled,

    #[error("plugin trigger is already disabled")]
    TriggerAlreadyDisabled,

    #[error("invalid column type for column '{column_name}', expected {expected}, got {got}")]
    InvalidColumnType {
        column_name: Arc<str>,
        expected: InfluxColumnType,
        got: InfluxColumnType,
    },

View on GitHub (pinned to 06200ef96b)