influxdata/influxdb · error · CacheError

unexpected error

Error message

unexpected error: {0}

What it means

CacheError::Unexpected wraps an anyhow::Error for errors that do not map to a specific cache failure mode, e.g. internal schema/IO issues. It signals a bug or an unexpected environmental failure inside the distinct cache subsystem rather than invalid user input.

Solutions

1. Inspect the wrapped anyhow message/chain (source) to identify the root cause
2. Retry the operation if the cause was transient; otherwise file an issue with the full error chain
3. Update the server/clients if a version mismatch is implicated

// Rust
match provider.new_cache(table_id, cols) {
    Err(ProviderError::Cache(CacheError::Unexpected(src))) => {
        error!(error = ?src, "unexpected distinct cache failure");
        // capture src.chain() for the bug report; retry only if transient
    }
    other => other,
}

When it happens

Trigger: Any internal failure while constructing or operating a DistinctCache that surfaces through anyhow, converted automatically via #[from] anyhow::Error.

Common situations: Underlying storage/catalog errors, unexpected schema states, or version mismatches inside the server that are not supposed to happen during normal operation.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• cache error
• must pass a non-empty set of column ids
• cache not found
• cannot overwrite an an existing cache
• cannot use a column of type

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

Appendix: source

Thrown at influxdb3_cache/src/distinct_cache/cache.rs:33

use influxdb3_catalog::catalog::{MaxAge, MaxCardinality, TableDefinition};
use influxdb3_id::{ColumnId, ColumnIdentifier};
use influxdb3_wal::{FieldData, Row};
use iox_time::TimeProvider;
use observability_deps::tracing::debug;
use schema::{InfluxColumnType, InfluxFieldType};

#[derive(Debug, thiserror::Error)]
pub enum CacheError {
    #[error("must pass a non-empty set of column ids")]
    EmptyColumnSet,
    #[error(
        "cannot use a column of type {attempted} in a distinct value cache, only \
                    tags and string fields can be used"
    )]
    NonTagOrStringColumn { attempted: InfluxColumnType },
    #[error("cannot overwrite an an existing cache: {message}")]
    ConfigurationMismatch { message: String },
    #[error("unexpected error: {0}")]
    Unexpected(#[from] anyhow::Error),
}

/// A cache for storing distinct values for a set of columns in a table
#[derive(Debug)]
pub(crate) struct DistinctCache {
    time_provider: Arc<dyn TimeProvider>,
    /// The maximum number of unique value combinations in the cache
    max_cardinality: usize,
    /// The maximum age for entries in the cache
    max_age: Duration,
    /// The fixed Arrow schema used to produce record batches from the cache
    schema: SchemaRef,
    /// Holds current state of the cache
    pub(crate) state: DistinctCacheState,
    /// The identifiers of the columns used in the cache
    column_ids: Vec<ColumnId>,
    /// The cache data, stored in a tree

View on GitHub (pinned to 06200ef96b)