influxdata/influxdb · error · PersisterError

failed to parse snapshot sequence number from filename

Error message

failed to parse snapshot sequence number from filename

What it means

PersisterError::InvalidSnapshotSequenceNumber is raised when the snapshot sequence number cannot be parsed out of a snapshot filename during enumeration. Snapshot files encode their sequence number in the name (parsed via crate::paths helpers); a name that does not contain a valid number breaks ordering of snapshots and is rejected. It is thrown from the persister while listing or resolving the latest snapshot.

Solutions

1. List the snapshot prefix and identify the object whose filename has no valid sequence number
2. Delete or rename the offending object to the canonical filename format
3. Re-verify snapshot ordering by restarting the writer and confirming it loads the latest snapshot cleanly
4. If files were copied from another environment, re-persist snapshots through the writer instead of copying raw objects

Example fix

// before
cp snapshot.json snapshots/snapshot.json
// after: name must embed the sequence number
cp snapshot.json snapshots/0000000042.persisted_snapshot.json

fn parse_snapshot_seq(name: &str) -> Option<u64> {
    name.split('.').next()?.parse::<u64>().ok()
}
// pre-scan the snapshot prefix and reject/repair files where parse_snapshot_seq is None

fn is_valid_snapshot_file(key: &object_store::path::Path) -> bool {
    key.filename().map(|f| parse_snapshot_seq(f).is_some()).unwrap_or(false)
}

match res {
    Err(PersisterError::InvalidSnapshotSequenceNumber) => {
        log::error("non-canonical snapshot filename in store; skipping/rebuilding");
    }
    other => other?,
}

When it happens

Trigger: Listing snapshot objects and parsing each filename for its sequence number; any file under the snapshot prefix whose name does not embed a parseable u64 sequence number triggers this when the persister builds SnapshotInfoFilePath/TableIndexPath metadata.

Common situations: Someone placed custom or corrupted files in the snapshot directory; a partially-uploaded file with a truncated name; migrating snapshots between InfluxDB3 versions that changed the filename convention.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

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

Related errors

• error from persister
• Failed to load table index snapshot from object store
• Failed to parse snapshot sequence number from filename
• Failed to parse table index snapshot path from object store…
• Failed to persist table index to object store

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

Appendix: source

Thrown at influxdb3_write/src/persister.rs:83

    #[error("parse int error: {0}")]
    ParseInt(#[from] std::num::ParseIntError),

    #[error("unexpected persister error: {0:?}")]
    Unexpected(#[from] anyhow::Error),

    #[error("table snapshot persistence task panicked: {0}")]
    TableSnapshotPersistenceTaskFailed(#[source] tokio::task::JoinError),

    #[error("snapshot manifest parse task panicked: {0}")]
    SnapshotParseTaskFailed(#[source] tokio::task::JoinError),

    #[error("table index error: {0}")]
    TableIndexPathError(#[source] crate::paths::PathError),

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

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

impl From<PersisterError> for DataFusionError {
    fn from(error: PersisterError) -> Self {
        match error {
            PersisterError::DataFusion(e) => e,
            PersisterError::ObjectStore(e) => DataFusionError::ObjectStore(Box::new(e)),
            PersisterError::ParquetError(e) => DataFusionError::ParquetError(Box::new(e)),
            _ => DataFusionError::External(Box::new(error)),
        }
    }
}

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

pub const DEFAULT_OBJECT_STORE_URL: &str = "iox://influxdb3/";
const MAX_CONCURRENT_CHECKPOINT_LOADS: usize = 10;

View on GitHub (pinned to 06200ef96b)