influxdata/influxdb · error · ProviderError

cache error

Error message

cache error: {0}

What it means

ProviderError::Cache wraps a CacheError (via #[from]) when a distinct-cache level failure propagates through the cache provider. It is the provider-layer envelope around errors like EmptyColumnSet, NonTagOrStringColumn, or ConfigurationMismatch.

Solutions

1. Match on ProviderError::Cache and handle the inner CacheError variant to produce a precise user message
2. Fix the underlying cause per the inner error (valid columns, non-empty set, no conflicting overwrite)
3. Log the full error chain for diagnostics

Example fix

// before
match provider.new_cache(table_id, cols) { Ok(c) => c, Err(e) => return Err(anyhow!(e)) }
// after
match provider.new_cache(table_id, cols) {
    Ok(c) => c,
    Err(ProviderError::Cache(inner)) => bail!("invalid distinct cache request: {inner}"),
    Err(ProviderError::CacheNotFound) => bail!("cache does not exist"),
    Err(e) => return Err(e.into()),
}

// Rust
match provider.new_cache(table_id, cols) {
    Ok(cache) => cache,
    Err(ProviderError::Cache(inner)) => bail!("distinct cache rejected: {inner}"),
    Err(ProviderError::CacheNotFound) => bail!("cache not found"),
    Err(ProviderError::Unexpected(e)) => bail!("unexpected: {e:#}"),
}

When it happens

Trigger: Any provider API call (new_cache, get_cache, etc.) whose underlying DistinctCache operation returns a CacheError, automatically converted into ProviderError::Cache.

Common situations: Creating caches with empty or non-string column lists, or redefining an existing cache with mismatched configuration, observed at the provider/HTTP API layer.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• must pass a non-empty set of column ids
• unexpected error
• 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/81d457831a1be2f3. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_cache/src/distinct_cache/provider.rs:17

use std::{collections::HashMap, sync::Arc, time::Duration};

use super::{
    CacheError,
    cache::{CreateDistinctCacheArgs, DistinctCache},
};
use arrow::datatypes::SchemaRef;
use influxdb3_catalog::catalog::{Catalog, CatalogEvent, CatalogUpdateReceiver, IfNotDeleted};
use influxdb3_id::{DbId, DistinctCacheId, TableId};
use influxdb3_wal::{WalContents, WalOp};
use iox_time::TimeProvider;
use observability_deps::tracing::error;
use parking_lot::RwLock;

#[derive(Debug, thiserror::Error)]
pub enum ProviderError {
    #[error("cache error: {0}")]
    Cache(#[from] CacheError),
    #[error("cache not found")]
    CacheNotFound,
    #[error("unexpected error: {0:#}")]
    Unexpected(#[from] anyhow::Error),
}

/// Triple nested map for storing a multiple distinct value caches per table.
///
/// That is, the map nesting is `database -> table -> cache id`
type CacheMap = RwLock<HashMap<DbId, HashMap<TableId, HashMap<DistinctCacheId, DistinctCache>>>>;

/// Provides the distinct value caches for the running instance of InfluxDB
#[derive(Debug)]
pub struct DistinctCacheProvider {
    pub(crate) time_provider: Arc<dyn TimeProvider>,
    pub(crate) catalog: Arc<Catalog>,
    pub(crate) cache_map: CacheMap,

View on GitHub (pinned to 06200ef96b)