influxdata/influxdb · critical · Error::WriteBufferInit

Failed to initialize table index cache: {}

Error message

Failed to initialize table index cache: {}

What it means

During `influxdb3 serve` startup, the table index cache is initialized from snapshots persisted in the object store before WAL snapshotting, retention, or hard deletion are allowed to run (the transformation from PersistedSnapshot to TableIndex needs a quiescent window). If table_index_cache.initialize() fails, the error is wrapped in Error::WriteBufferInit and the server refuses to start. The '{}' in the message carries the underlying cause — object store read failure, unreadable/corrupt snapshot, or deserialization error.

Source

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

        table_index_cache_config,
        Arc::clone(&object_store),
    );

    info!(
        node_id = &*node_id,
        max_entries = ?table_index_cache_config.max_entries,
        concurrency_limit = table_index_cache_config.concurrency_limit,
        "Initializing table index cache"
    );

    // Initialize table index cache from any existing snapshots
    //
    // This needs to happen before WAL snapshotting, retention handling, or hard deletion could
    // begin executing so we have a quiescent time during which we can transform
    // `PersistedSnapshot` to `TableIndexSnapshot` to `TableIndex` to completion.
    table_index_cache.initialize().await.map_err(|e| {
        warn!("Failed to initialize table index cache: {}", e);
        Error::WriteBufferInit(anyhow::anyhow!(
            "Failed to initialize table index cache: {}",
            e
        ))
    })?;

    // Create and start the retention period handler
    let retention_handler = Arc::new(RetentionPeriodHandler::new(
        table_index_cache.clone(),
        Arc::clone(&catalog),
        Arc::clone(&time_provider) as _,
        retention_check_interval,
        node_id,
    ));

    tokio::spawn(async move {
        retention_handler
            .background_task(retention_handler_token)
            .await

View on GitHub (pinned to d28e26e048)

Solutions

1. Read the text after the colon in the log line — it names the real failure (auth, not-found, corrupt data, decode error)
2. Verify object store configuration (endpoint, bucket, credentials) and that --node-id matches the node that wrote the data
3. If the underlying error indicates corruption from a crashed run, follow the InfluxDB 3 docs on removing the table index snapshot objects so the cache rebuilds (the source data lives in the WAL/parquet files)
4. If startup broke right after a version change, roll back to the previous binary version first, let it start cleanly, then plan the upgrade

Example fix

# before: wrong bucket / node-id -> snapshot init fails
influxdb3 serve --object-store s3://wrong-bucket --node-id n2

# after: same bucket and node-id the data was written with
influxdb3 serve --object-store s3://original-bucket --node-id n1

# pre-flight: confirm the object store is reachable with these creds before serve
aws s3 ls "s3://${BUCKET}/" >/dev/null 2>&1 \
  || { echo "object store unreachable — fix creds/bucket before starting" >&2; exit 1; }
influxdb3 serve --object-store "s3://${BUCKET}" --node-id "${NODE_ID}"

# systemd Restart + StartLimit gives bounded retry for transient object-store blips at boot
[Service]
ExecStart=/usr/bin/influxdb3 serve --object-store s3://bucket --node-id n1
Restart=on-failure
RestartSec=10

When it happens

Trigger: `influxdb3 serve` where the object store's table index snapshots cannot be read or parsed: wrong bucket/credentials/endpoint, a different --node-id than the data was written under, snapshots corrupted or half-written by a previous crash, or a snapshot format left incompatible by an upgrade/downgrade.

Common situations: Pointing serve at the wrong S3 bucket or using rotated credentials; restoring from backup selectively (snapshots copied inconsistently with catalog/WAL); swapping versions of the binary; transient object-store outage exactly at boot.

Related errors

• Measurement name cannot contain spaces
• {key_type} key cannot be empty
• {key_type} key '{key}' cannot contain spaces
• {key_type} key '{key}' cannot contain commas
• {key_type} key '{key}' cannot contain equals signs

AI-assisted analysis of influxdata/influxdb@d28e26e048 (2026-08-16). Data as JSON: /api/errors/3887dac09b250eab. Report an issue: GitHub.