influxdata/influxdb · error · Error

error in distinct value cache

Error message

error in distinct value cache: {0}

What it means

Wraps distinct_cache::ProviderError (#[from]) — a failure in the distinct value cache subsystem used to enforce tag uniqueness constraints. Raised when updating or querying the distinct value cache during writes fails.

Solutions

1. Inspect the inner ProviderError for the exact cause
2. Reduce tag cardinality or drop unneeded tags from the written data
3. Restart the server to rebuild cache state if it is corrupted
4. Retry the write once the cache subsystem recovers

// pre-check cardinality of tag sets before writing
if estimated_tag_cardinality(tags) > MAX_DISTINCT_VALUES {
    return Err("tag cardinality too high for distinct cache");
}

fn is_distinct_cache_error(err: &WriteBufferError) -> bool {
    matches!(err, WriteBufferError::DistinctCacheError(_))
}

match buffer.write(db, lines) {
    Err(WriteBufferError::DistinctCacheError(e)) => {
        eprintln!("distinct cache failure: {e}; reduce tag cardinality or retry");
    }
    other => other?,
}

When it happens

Trigger: A write triggers a distinct-value cache operation (e.g. checking tag value cardinality/uniqueness) and the underlying cache provider errors — memory pressure, lock contention, or internal provider failure.

Common situations: High-cardinality tag sets stressing the cache; concurrent writers contending on the cache; bugs or resource limits in the cache provider after long uptimes.

Related errors

• cache error
• cannot overwrite an an existing cache
• cannot use a column of type
• Cannot write
• cannot write to soft-deleted database

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

Appendix: source

Thrown at influxdb3_write/src/write_buffer/mod.rs:137

    #[error("table '{db_name}.{table_name}' already exists")]
    TableAlreadyExists {
        db_name: Arc<str>,
        table_name: Arc<str>,
    },

    #[error("tried accessing column with name ({0}) that does not exist")]
    ColumnDoesNotExist(String),

    #[error(
        "updating catalog on delete of last cache failed, you will need to delete the cache \
        again on server restart"
    )]
    DeleteLastCache(#[source] CatalogError),

    #[error("error from wal: {0}")]
    WalError(#[from] influxdb3_wal::Error),

    #[error("error in distinct value cache: {0}")]
    DistinctCacheError(#[from] distinct_cache::ProviderError),

    #[error("cannot write to a compactor-only server")]
    NoWriteInCompactorOnly,

    #[error("error: {0}")]
    AnyhowError(#[from] anyhow::Error),

    #[error("write not allowed on internal database")]
    InternalDbWriteNotAllowed,
}

pub type Result<T, E = Error> = std::result::Result<T, E>;

#[derive(Debug)]
pub struct WriteRequest<'a> {
    pub db_name: DatabaseName,
    pub line_protocol: &'a str,

View on GitHub (pinned to 06200ef96b)