influxdata/influxdb · error · ProviderError

cache not found

Error message

cache not found

What it means

ProviderError::CacheNotFound is returned by the distinct value cache provider when a lookup is requested for a cache id that does not exist under the given database/table in the triple nested map (database -> table -> cache id). The provider stores multiple distinct value caches per table, and this variant signals the requested entry is absent rather than that a cache operation failed. It is thrown by the library when callers reference a cache by name/id that was never created or has been removed.

Solutions

1. Check the cache id/name for typos and confirm it matches the one used at creation time
2. Verify the cache exists for the exact database and table pair you are querying (the map is nested database -> table -> cache id)
3. Create the distinct cache (via the provider's create/add API) before reading or writing it
4. Check that the cache was not deleted by a concurrent operation or migration and recreate it if needed

Example fix

// before
let cache = provider.get_cache(db, table, cache_id)?;
// after
match provider.get_cache(db, table, cache_id) {
    Ok(cache) => { /* use cache */ }
    Err(ProviderError::CacheNotFound) => {
        let cache = provider.create_cache(db, table, cache_id, config)?;
    }
    Err(e) => return Err(e.into()),
}

// Rust: check existence before use
if !provider.has_cache(db, table, cache_id) {
    return Err(format!("distinct cache {cache_id} not found for {db}.{table}"));
}

fn is_cache_not_found(err: &ProviderError) -> bool {
    matches!(err, ProviderError::CacheNotFound)
}

match provider.get_cache(db, table, cache_id) {
    Ok(c) => c,
    Err(ProviderError::CacheNotFound) => initialize_default_cache(),
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: Calling provider methods such as get_cache/cache lookup with a cache_id that was never created for that database and table; referencing a distinct cache after it was deleted; passing the wrong cache id or a cache that belongs to a different database/table pair.

Common situations: Typo in the cache name/id in application config; querying a cache before its creation code ran; environment drift where the cache creation migration was not applied; attempting to write or read a distinct cache after a drop operation; using a cache id from one table against another table.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• cache error
• error in last cache
• failed to initialize distinct cache
• failed to initialize last cache
• invalid cache size

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

Appendix: source

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

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)