influxdata/influxdb · error · TableIndexError

Failed to parse snapshot sequence number from filename

Error message

Failed to parse snapshot sequence number from filename

What it means

TableIndexError::InvalidSnapshotSequenceNumber is raised when the snapshot sequence number cannot be parsed from a snapshot object's filename. Snapshot files embed a monotonically increasing SnapshotSequenceNumber used for ordering and deduplication; a filename whose numeric segment is missing or non-numeric cannot be ordered. This variant carries no source error — parsing simply failed.

Solutions

1. Inspect the failing filename and fix or remove the malformed object.
2. Delete foreign/legacy files from the snapshot prefix that don't carry a valid numeric sequence segment.
3. Skip unparsable filenames with a warning rather than failing the whole listing.
4. Ensure all writers run a compatible InfluxDB 3 version so filenames follow the same schema.

Example fix

// before
let seq: SnapshotSequenceNumber = parse_seq(name).unwrap();
// after
match parse_seq(name) {
    Ok(seq) => process(seq),
    Err(_) => warn!(%name, "skipping snapshot with unparsable sequence number"),
}

fn parse_seq_from_filename(name: &str) -> Option<u64> {
    name.rsplit('_').next()?.trim_end_matches(".json").parse::<u64>().ok()
}
// only process files where this returns Some

match parse_seq(name) {
    Some(seq) => process(seq),
    None => { warn!(%name, "invalid snapshot sequence number; skipping"); continue; }
}

When it happens

Trigger: Iterating snapshot objects and parsing the sequence number out of the filename (e.g. splitting on '_' or extracting a numeric suffix) where the segment is absent, corrupted, or not a valid u64.

Common situations: Files hand-renamed or edited in the bucket; truncated filenames from an interrupted write; legacy snapshot naming from an older version; foreign files dropped into the snapshot prefix.

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

• failed to parse snapshot sequence number from filename
• Failed to parse table index path from object store path
• Failed to parse table index snapshot path from object store…
• Failed to split persisted snapshot into table snapshots
• ' ' is a reserved column

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

Appendix: source

Thrown at influxdb3_write/src/table_index.rs:67

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

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

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

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

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

    #[error("Object store operation failed")]
    ObjectStore(#[source] object_store::Error),

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

pub type Result<T> = std::result::Result<T, TableIndexError>;

/// An partial, incremental index into a given database/table. Should not be used to make decisions

View on GitHub (pinned to 06200ef96b)