influxdata/influxdb · error · ProviderError

unexpected error

Error message

unexpected error: {0:#}

What it means

ProviderError::Unexpected wraps any anyhow::Error raised inside the distinct cache provider that does not map to a specific cache error, exposing it with the format "unexpected error: {0:#}". It indicates an internal/unanticipated failure (e.g. poisoning, unexpected state, lower-level issue) rather than a normal caller-facing condition. The {0:#} alternate formatting renders the anyhow error chain readably.

Solutions

1. Inspect the wrapped anyhow error chain in the message ({0:#} prints the full context chain) to find the root cause
2. Check for concurrent operations on the same cache (create/delete/write races) and serialize them
3. Reproduce with the same inputs and file an issue with the error chain if it looks like a library bug
4. Pin or bump the influxdb3_cache version to rule out a known regression

Example fix

// before
let cache = provider.create_cache(db, table, id, cfg)?; // Unexpected bubbles up opaquely
// after
if let Err(e) = provider.create_cache(db, table, id, cfg) {
    tracing::error!(error = ?e, "distinct cache provider failed");
    return Err(e);
}

fn is_unexpected(err: &ProviderError) -> bool {
    matches!(err, ProviderError::Unexpected(_))
}

match result {
    Err(ProviderError::Unexpected(cause)) => {
        // log full anyhow chain and escalate — this is an internal bug
        tracing::error!("unexpected provider failure: {cause:#}");
    }
    other => other?,
}

When it happens

Trigger: Any ?-propagated anyhow::Error inside provider code paths (e.g. unexpected internal state while creating, deleting, or reading a distinct cache); bugs in the cache subsystem that are not classified as CacheError.

Common situations: Hitting a code path the library authors did not anticipate, such as concurrent creation racing with deletion; internal invariants broken in the nested map; bugs surfaced after a library version upgrade; misconfiguration that only fails deep inside provider internals.

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

• unexpected persister error
• error
• lost backend
• unexpected
• unexpected batch schema mismatch: expected

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

Appendix: source

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

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,
}

impl DistinctCacheProvider {
    /// Initialize a [`DistinctCacheProvider`] from a [`Catalog`], populating the provider's

View on GitHub (pinned to 06200ef96b)