influxdata/influxdb · error · Error

failed to initialize distinct cache

Error message

failed to initialize distinct cache: {0:#}

What it means

Display message of the `Error::InitializeDistinctCache` variant, wrapping an `influxdb3_cache::distinct_cache::ProviderError` (#[source], printed with alternate/pretty {0:#}) from building the distinct-value cache provider at startup. Like the last cache, it is driven by per-table cache specifications.

Solutions

1. Inspect the pretty-printed ProviderError ({0:#}) to identify the failing cache
2. Drop and recreate the distinct cache with columns valid in the current schema
3. Confirm the cached column's type is supported by the distinct cache
4. Fix max size/cardinality parameters to accepted ranges

Example fix

// before
CREATE DISTINCT CACHE ON "mytable"(region) ; -- region column dropped
// after
DROP DISTINCT CACHE ON "mytable";
CREATE DISTINCT CACHE ON "mytable"(tag1) ; -- existing column of supported type

-- verify distinct cache columns still exist and are supported types
-- before restarting the server with existing cache specs

match serve_result {
    Err(Error::InitializeDistinctCache(src)) => eprintln!("distinct cache init failed: {src:#}"),
    ...
}

When it happens

Trigger: During serve startup, a distinct cache specification for some table cannot be initialized — e.g. the cached column no longer exists, or the column type is unsupported for a distinct cache.

Common situations: Schema drift: the table lost or renamed the column referenced by the distinct cache; max-cardinality/size parameters invalid; cache provider constructed against an incompatible catalog.

Related errors

• failed to initialize last cache
• cache not found
• column id in series key should be valid
• Error creating record batch
• error from table buffer

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

Appendix: source

Thrown at influxdb3/src/commands/serve.rs:150

    #[error("Token error: {0}")]
    TokenError(CatalogError),

    #[error("Write buffer error: {0}")]
    WriteBuffer(#[from] influxdb3_write::write_buffer::Error),

    #[error("invalid token: {0}")]
    InvalidToken(#[from] hex::FromHexError),

    #[error("failed to initialize write buffer: {0:?}")]
    WriteBufferInit(#[source] anyhow::Error),

    #[error("failed to initialize catalog: {0}")]
    InitializeCatalog(#[source] CatalogError),

    #[error("failed to initialize last cache: {0}")]
    InitializeLastCache(#[source] last_cache::Error),

    #[error("failed to initialize distinct cache: {0:#}")]
    InitializeDistinctCache(#[source] influxdb3_cache::distinct_cache::ProviderError),

    #[error("lost backend")]
    LostBackend,

    #[error("lost HTTP/gRPC service")]
    LostHttpGrpc,

    #[error("lost admin token recovery service")]
    LostAdminTokenRecovery,

    #[error("tls requires both a cert and a key file to be passed in to work")]
    NoCertOrKeyFile,

    #[error("table cache index initialization failed: {0}")]
    TableIndexCacheInitialization(
        #[source] influxdb3_write::table_index_cache::TableIndexCacheError,
    ),

View on GitHub (pinned to 06200ef96b)