influxdata/influxdb · error · PathError

Invalid sequence number in

Error message

Invalid sequence number in {context}: {filename}

What it means

PathError::InvalidSequenceNumber indicates that a parquet file path or its parsed sequence number component is invalid in the given context. The write path module parses filenames like `<table_id>-<date>-<hour>-<seq>.parquet` and validates the embedded sequence number; when the component cannot be parsed as a valid u64 or is malformed, this error is returned with the offending filename and the operation context.

Solutions

1. Inspect the offending filename reported in the error and ensure it matches the canonical influxdb3 parquet naming pattern with a numeric sequence segment.
2. Remove or quarantine the malformed file from the object store so path parsing skips it.
3. Verify you are not renaming or rewriting parquet files outside of the influxdb3 writer.
4. Check that all nodes writing to the bucket run compatible influxdb3 versions producing the same file layout.

Example fix

// before: manually copied file with broken name
prometheus-2024-01-01-abc.parquet
// after: canonical layout with numeric sequence
9f2b7e1c-000001.parquet  (table uuid - nanosecond timestamp - sequence)

fn is_valid_parquet_name(name: &str) -> bool {
    let base = name.strip_suffix(".parquet").unwrap_or(name);
    base.split('-').last().map_or(false, |seq| seq.parse::<u64>().is_ok())
}

When it happens

Trigger: Constructing or parsing a QueryDatabaseResponse / persisted parquet file path whose sequence-number segment is not a valid integer, e.g. calling paths helpers on a hand-named or corrupted file in the object store that does not follow the canonical `<uuid>-<timestamp>-<seq>.parquet` layout.

Common situations: Files renamed or written by external tools directly into the object store bucket; partially-uploaded parquet files left by a crashed writer; copying files across environments while altering names; older file layouts produced by previous influxdb3 versions no longer matching the current parser.

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.

Related errors

• parse int error
• is not a valid data type, values are int64, uint64…
• another process has written to the WAL ahead of this one
• Cannot parse object store config
• Could not find '_'

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

Appendix: source

Thrown at influxdb3_write/src/paths.rs:24

use regex::Regex;
use std::ops::Deref;
use std::str::FromStr;
use std::sync::{Arc, LazyLock};
use thiserror::Error;

/// Errors that can occur when parsing paths
#[derive(Debug, Error)]
pub enum PathError {
    #[error("Invalid path format: expected {expected}, got: {actual}")]
    InvalidFormat { expected: String, actual: String },

    #[error("Invalid database ID: {0}")]
    InvalidDbId(String),

    #[error("Invalid table ID: {0}")]
    InvalidTableId(String),

    #[error("Invalid sequence number in {context}: {filename}")]
    InvalidSequenceNumber { context: String, filename: String },
}

/// File extension for parquet files
pub const PARQUET_FILE_EXTENSION: &str = "parquet";

/// File extension for snapshot info files
pub const SNAPSHOT_INFO_FILE_EXTENSION: &str = "info.json";

/// File extension for checkpoint files
pub const CHECKPOINT_FILE_EXTENSION: &str = "checkpoint.json";

fn object_store_file_stem(n: u64) -> u64 {
    u64::MAX - n
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParquetFilePath(ObjPath);

View on GitHub (pinned to 06200ef96b)