{"record":{"id":"3887dac09b250eab","repo":"influxdata/influxdb","slug":"failed-to-initialize-table-index-cache","errorCode":null,"errorMessage":"Failed to initialize table index cache: {}","messagePattern":"Failed to initialize table index cache: (.+?)","errorType":"exception","errorClass":"Error::WriteBufferInit","httpStatus":null,"severity":"critical","filePath":"influxdb3/src/commands/serve.rs","lineNumber":1594,"sourceCode":"        table_index_cache_config,\n        Arc::clone(&object_store),\n    );\n\n    info!(\n        node_id = &*node_id,\n        max_entries = ?table_index_cache_config.max_entries,\n        concurrency_limit = table_index_cache_config.concurrency_limit,\n        \"Initializing table index cache\"\n    );\n\n    // Initialize table index cache from any existing snapshots\n    //\n    // This needs to happen before WAL snapshotting, retention handling, or hard deletion could\n    // begin executing so we have a quiescent time during which we can transform\n    // `PersistedSnapshot` to `TableIndexSnapshot` to `TableIndex` to completion.\n    table_index_cache.initialize().await.map_err(|e| {\n        warn!(\"Failed to initialize table index cache: {}\", e);\n        Error::WriteBufferInit(anyhow::anyhow!(\n            \"Failed to initialize table index cache: {}\",\n            e\n        ))\n    })?;\n\n    // Create and start the retention period handler\n    let retention_handler = Arc::new(RetentionPeriodHandler::new(\n        table_index_cache.clone(),\n        Arc::clone(&catalog),\n        Arc::clone(&time_provider) as _,\n        retention_check_interval,\n        node_id,\n    ));\n\n    tokio::spawn(async move {\n        retention_handler\n            .background_task(retention_handler_token)\n            .await","sourceCodeStart":1576,"sourceCodeEnd":1612,"githubUrl":"https://github.com/influxdata/influxdb/blob/d28e26e048401c53cbb98cf2d6ab0cf1e98048ca/influxdb3/src/commands/serve.rs#L1576-L1612","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Read the text after the colon in the log line — it names the real failure (auth, not-found, corrupt data, decode error)","Verify object store configuration (endpoint, bucket, credentials) and that --node-id matches the node that wrote the data","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)","If startup broke right after a version change, roll back to the previous binary version first, let it start cleanly, then plan the upgrade"],"exampleFix":"# before: wrong bucket / node-id -> snapshot init fails\ninfluxdb3 serve --object-store s3://wrong-bucket --node-id n2\n\n# after: same bucket and node-id the data was written with\ninfluxdb3 serve --object-store s3://original-bucket --node-id n1","handlingStrategy":"retry","validationCode":"# pre-flight: confirm the object store is reachable with these creds before serve\naws s3 ls \"s3://${BUCKET}/\" >/dev/null 2>&1 \\\n  || { echo \"object store unreachable — fix creds/bucket before starting\" >&2; exit 1; }\ninfluxdb3 serve --object-store \"s3://${BUCKET}\" --node-id \"${NODE_ID}\"","typeGuard":null,"tryCatchPattern":"# systemd Restart + StartLimit gives bounded retry for transient object-store blips at boot\n[Service]\nExecStart=/usr/bin/influxdb3 serve --object-store s3://bucket --node-id n1\nRestart=on-failure\nRestartSec=10","preventionTips":["Always start with the same --object-store bucket and --node-id the data was written under","Stop the server cleanly before upgrades; keep binary version pinned until tested","Back up the object store consistently (catalog + snapshots + WAL together), never selectively","On startup failure, read the underlying error after the colon before changing anything"],"tags":["influxdb","server-startup","object-store","table-index","cache"],"backgroundTag":"server-startup-failure","analyzedSha":"d28e26e048401c53cbb98cf2d6ab0cf1e98048ca","analyzedAt":"2026-08-16T19:53:34.623Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}