influxdata/influxdb · error · TableIndexCacheError

Failed to list table index snapshots from object store

Error message

Failed to list table index snapshots from object store

What it means

TableIndexCacheError::ListSnapshots, thrown when an object_store List call fails while enumerating table index snapshot objects under a table index prefix. The cache must list snapshots to hydrate a TableIndex; if the underlying store returns an error (network, auth, throttling), listing aborts with this variant.

Solutions

1. Retry the operation — object store list failures are frequently transient; the RetryableObjectStore wrapper used here helps but does not eliminate all failures
2. Verify object store credentials, endpoint, region, and bucket/container name in the configuration
3. Check network connectivity and DNS from the node to the object store endpoint
4. Inspect the inner object_store::Error via #[source] for the exact provider error code (e.g. NoSuchBucket, AccessDenied)

Example fix

// before: single attempt
let snapshots = cache.list_snapshots(&index_path).await?;
// after: bounded retry for transient store errors
let snapshots = retry_with_backoff(3, Duration::from_millis(200), ||
    cache.list_snapshots(&index_path)
).await.map_err(|e| warn!(error=?e, "listing index snapshots failed"))?;

// preflight: verify store reachability and credentials
store.head(&ObjPath::from("healthcheck")).await
    .map_err(|e| format!("object store unavailable: {e}"))?;

match err {
    TableIndexCacheError::ListSnapshots(e)
        if e.is_transient() => retry_with_backoff(3, op).await?,
    TableIndexCacheError::ListSnapshots(e) => {
        error!(source=?e, "permanent list failure — check credentials/bucket");
        return Err(e.into());
    }
    _ => unreachable!(),
}

When it happens

Trigger: Calling code that builds/refreshes a TableIndex from the object store: listing objects under the table-index snapshot prefix (e.g. while populating the LRU cache on a cache miss or during startup recovery) when the object_store::ObjectStore::list stream yields an error.

Common situations: S3/GCS/Azure transient 5xx or throttling during startup; wrong bucket/container credentials; region misconfiguration; bucket deleted or renamed; network partition between the InfluxDB 3 node and the object store.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• Failed to list object store metadata
• Failed to load table index conversion marker bytes from…
• Failed to put initial table index conversion marker to…
• Failed to create table index from object store
• Failed to delete parquet file

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

Appendix: source

Thrown at influxdb3_write/src/table_index_cache.rs:69

    #[error("Object meta is missing filename")]
    MissingFilename,

    #[error("Failed to parse snapshot sequence number from filename")]
    InvalidSnapshotSequenceNumber,

    #[error("Unexpected error")]
    Unexpected(#[source] anyhow::Error),

    #[error("Table snapshot persistence task failed")]
    TableSnapshotPersistenceTaskFailed(#[source] tokio::task::JoinError),

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

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

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

    #[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")]
    UpdateTaskFailed(#[source] tokio::task::JoinError),

    #[error("Failed to list object store metadata")]
    ListMetasError(#[source] object_store::Error),

    #[error("Failed to load table index conversion marker bytes from object store")]
    LoadConversionMarkerBytesError(#[source] object_store::Error),

    #[error("Failed to serialize initial table index conversion marker")]
    SerializeConversionMarkerError(#[source] serde_json::Error),

    #[error("Failed to put initial table index conversion marker to object store")]

View on GitHub (pinned to 06200ef96b)