influxdata/influxdb · error · TableIndexCacheError

Failed to parse snapshot sequence number from filename

Error message

Failed to parse snapshot sequence number from filename

What it means

TableIndexCacheError::InvalidSnapshotSequenceNumber is returned when the snapshot sequence number cannot be parsed from a snapshot file's name. Filenames encode an inverted sequence number (u64::MAX - seq) and if the name does not match the expected pattern, conversion of persisted snapshots cannot order or checkpoint progress.

Solutions

List the snapshot info prefix and remove/rename any files that do not match the canonical snapshot filename pattern.
Verify the files were produced by a compatible InfluxDB 3 version; migrate or delete files from incompatible versions.
Check for tooling (backups, sync jobs) that copies auxiliary files into the snapshot directory and exclude them.
Restart the node after cleaning so the conversion re-lists only valid snapshots.

Example fix

// before: stray file snapshot-000123.bak in the snapshot dir causes parse failure
// after: keep only canonical files
mv snapshot-000123.bak /backup/ && influxdb3 run

Defensive patterns

Strategy: validation

Validate before calling

// verify a filename matches the snapshot naming scheme before startup
fn looks_like_snapshot(name: &str) -> bool {
    name.starts_with("snapshot") && name.split('-').last().map_or(false, |s| s.parse::<u64>().is_ok())
}

Type guard

fn parse_seq(name: &str) -> Option<u64> {
    name.rsplit('-').next()?.parse::<u64>().ok()
}

Try / catch

match SnapshotInfoFilePath::parse_sequence_number(path) {
    Some(seq) => use_seq(seq),
    None => {
        warn!("non-snapshot file {path} in snapshot dir; ignoring");
    }
}

Prevention

Keep backups and editor temp files out of the snapshot directory
Enforce the canonical snapshot filename pattern in any tooling that writes there
Validate file naming after version migrations or manual restores

When it happens

Trigger: SnapshotInfoFilePath::parse_sequence_number returns None for the last listed snapshot meta's filename during split_persisted_snapshots_to_table_index_snapshots (table_index_cache.rs:442).

Common situations: Foreign or renamed files dropped into the snapshot directory (e.g. backup copies like snapshot-000123.bak, editor temp files, files from a different InfluxDB version with a different naming scheme).

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

Thrown at influxdb3_write/src/table_index_cache.rs:54

};

use thiserror::Error;

#[derive(Debug, Error)]
pub enum TableIndexCacheError {
    #[error("Object store operation failed")]
    ObjectStore(#[source] object_store::Error),

    #[error("JSON serialization/deserialization failed")]
    Json(#[source] serde_json::Error),

    #[error("TableIndex operation failed")]
    TableIndex(#[source] crate::table_index::TableIndexError),

    #[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")]

View on GitHub (pinned to 06200ef96b)