influxdata/influxdb · error · TableIndexError

Failed to persist table index to object store

Error message

Failed to persist table index to object store

What it means

TableIndexError::PersistIndex is raised when writing a table index object to the configured object store (S3, GCS, Azure, local file store) fails. The table index is an incremental per-database/table index persisted alongside snapshots; if the underlying object_store::Error (from a put/write operation) bubbles up, this variant wraps it. It indicates the index could not be durably written, so the index may be stale or missing for that table.

Solutions

1. Inspect the wrapped #[source] object_store::Error to identify the root cause (auth, throttling, connectivity).
2. Verify the object store credentials/IAM policy allow writes (PutObject, CompleteMultipartUpload) on the target bucket.
3. Check network/proxy connectivity to the storage endpoint and retry; wrap writes with the RetryableObjectStore already used in the codebase.
4. Confirm the bucket/container exists and the configured URL/prefix is correct.
5. Check for storage quota or size-limit errors and free space or adjust limits.

Example fix

// before: unguarded persist
index_cache.persist_to_object_store(&store).await?;
// after: retry transient failures and log the source
match index_cache.persist_to_object_store(&store).await {
    Err(TableIndexError::PersistIndex(e)) if e.is_retryable() => {
        retry_with_backoff(|| index_cache.persist_to_object_store(&store).await).await?
    }
    other => other?,
}

// before writes, verify store writability
let probe = object_store::path::Path::from("_healthcheck/probe");
store.put(&probe, Bytes::from_static(b"ok")).await?;
store.delete(&probe).await?;

match err {
    TableIndexError::PersistIndex(e) if e.is_retryable() => retry_with_backoff(...).await,
    TableIndexError::PersistIndex(e) => fail_fast_with_source(e),
    other => return other,
}

When it happens

Trigger: Calling the table index update/snapshotting code path that issues an object_store put (e.g. ObjectStore::put/put_multipart for a TableIndexPath object) and the store returns a network, permission, throttling, or bucket-missing error.

Common situations: Object store credentials lack PutObject/put permission on the bucket; transient network outage or S3 503/timeout; bucket misconfigured or deleted; object store size/quota limits hit; local file store path unwritable in dev environments.

Related errors

• error from wal
• error from persister
• Failed to create table index from object store
• Failed to delete parquet file
• Failed to delete table index snapshot from object store

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

Appendix: source

Thrown at influxdb3_write/src/table_index.rs:43

    #[error("Failed to deserialize table index")]
    SerializeIndex(#[source] serde_json::Error),

    #[error("Failed to deserialize table index")]
    DeserializeIndex(#[source] serde_json::Error),

    #[error("Failed to list table index snapshots from object store")]
    ListSnapshots(#[source] object_store::Error),

    #[error("Failed to list table indices from object store")]
    ListIndices(#[source] object_store::Error),

    #[error("Failed to load table index snapshot from object store")]
    LoadSnapshot(#[source] object_store::Error),

    #[error("Failed to deserialize table index snapshot")]
    DeserializeSnapshot(#[source] serde_json::Error),

    #[error("Failed to persist table index to object store")]
    PersistIndex(#[source] object_store::Error),

    #[error("Failed to delete table index snapshot from object store")]
    DeleteSnapshot(#[source] object_store::Error),

    #[error("Cannot merge table indices with mismatched identifiers: {expected} != {actual}")]
    MergeMismatch {
        expected: TableIndexId,
        actual: TableIndexId,
    },

    #[error("Failed to parse table index path from object store path")]
    TableIndexPath(#[source] crate::paths::PathError),

    #[error("Failed to parse table index snapshot path from object store path")]
    TableIndexSnapshotPath(#[source] crate::paths::PathError),

    #[error("Failed to update table index: join task failed")]

View on GitHub (pinned to 06200ef96b)