influxdata/influxdb · error · CacheError

cannot overwrite an an existing cache

Error message

cannot overwrite an an existing cache: {message}

What it means

CacheError::ConfigurationMismatch is returned when trying to create a distinct cache that would overwrite an existing cache with a different configuration. The cache name already exists and the requested definition (columns, table) does not match, so the provider refuses the silent overwrite. Note the message contains a typo ('an an').

Solutions

1. Drop the existing cache first (DROP DISTINCT CACHE / provider.delete_cache) then recreate it with the new configuration
2. Reuse the existing cache if the current configuration is acceptable
3. Use a new cache name for the different configuration

Example fix

-- before
CREATE DISTINCT CACHE "events_cache" ON events (host, region); -- exists with different columns
-- after
DROP DISTINCT CACHE "events_cache";
CREATE DISTINCT CACHE "events_cache" ON events (host, region);

// Check for an existing cache with the same name and compare its definition before creating
let existing = provider.get_cache(table_id, &cache_name);
if let Ok(c) = existing { /* compare columns/table before calling new_cache */ }

// Rust
match provider.new_cache(table_id, cols) {
    Err(ProviderError::Cache(CacheError::ConfigurationMismatch { message })) => {
        warn!(%message, "cache exists with different config; dropping and recreating");
        provider.delete_cache(table_id, &cache_name)?;
        provider.new_cache(table_id, cols)
    }
    other => other,
}

When it happens

Trigger: Calling create_cache/new_cache with a cache name that already exists but specifying different columns or table than the existing cache definition.

Common situations: Re-running a CREATE DISTINCT CACHE statement with edited column lists; infrastructure-as-code applying a modified cache definition over an existing one.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• cache error
• cannot use a column of type
• error in distinct value cache
• must pass a non-empty set of column ids
• unexpected error

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

Appendix: source

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

use indexmap::IndexMap;
use influxdb3_catalog::catalog::legacy;
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

View on GitHub (pinned to 06200ef96b)