influxdata/influxdb · critical · Error

table cache index initialization failed

Error message

table cache index initialization failed: {0}

What it means

Wraps a `TableIndexCacheError` from influxdb3_write that occurred while initializing the table index cache during server startup. The table index cache must be fully initialized before WAL snapshotting, retention, or hard deletion start, so a failure here aborts startup.

Solutions

1. Read the chained #[source] TableIndexCacheError message for the underlying cause.
2. Check data-directory disk health and permissions; verify WAL files are not corrupted.
3. Restore the node's data directory from backup if WAL/parquet data is corrupt.
4. Upgrade influxdb3; if the cause looks like a bug, file an issue with logs.

null

null

match result {
    Err(Error::TableIndexCacheInitialization(src)) => {
        eprintln!("table index cache init failed: {src}");
        // inspect src (TableIndexCacheError) for root cause
    }
    ...
}

When it happens

Trigger: `table_index_cache.initialize().await` returns Err during serve startup, e.g. because loading persisted table definitions from the WAL/parquet files fails or the underlying write buffer is corrupt.

Common situations: Corrupted or truncated WAL files, schema/catalog data unreadable on disk, or version-downgrade scenarios where persisted snapshots cannot be transformed to table indexes.

Related errors

• Failed to initialize table index cache
• can only accept once
• failed to initialize distinct cache
• failed to initialize last cache
• failed to initialize write buffer

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

Appendix: source

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

    #[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,
    ),

    #[error(
        "environment variable {0} (named by --node-id-from-env / INFLUXDB3_NODE_ID_FROM_ENV) \
        must be set to a valid node id"
    )]
    NodeIdEnvVarMissing(String),

    #[error(
        "Python environment initialization failed: {0}\nPlease ensure Python and pip package manager is installed"
    )]
    PythonEnvironmentInitialization(
        #[source] influxdb3_processing_engine::environment::PluginEnvironmentError,
    ),
}

View on GitHub (pinned to 06200ef96b)