influxdata/influxdb · error · PathError

Invalid path format: expected

Error message

Invalid path format: expected {expected}, got: {actual}

What it means

PathError::InvalidFormat is produced by the paths module when a storage path string does not match the expected structural pattern (expected vs actual are embedded in the message). The paths module parses object-store keys for databases, tables, and files, and this error signals the shape itself was wrong before any component could be interpreted.

Solutions

  1. Compare the `expected` and `actual` values in the message to see which layout was assumed
  2. Remove or move foreign/legacy objects out of the paths being scanned
  3. Ensure the writer and reader use compatible influxdb3 versions so path layouts match
  4. Add explicit filtering of object keys before parsing so only matching prefixes are parsed

Example fix

// before
for obj in list { let p = DbPath::parse(obj.location)?; } // fails on foreign keys
// after
for obj in list.filter(|o| o.location.prefix_starts_with(&Path::from("db"))) {
    let p = DbPath::parse(obj.location)?;
}
Defensive patterns

Strategy: try-catch

Validate before calling

fn matches_prefix(key: &str, prefix: &str, segments: usize) -> bool {
    key.starts_with(prefix) && key.split('/').count() == segments
}

Type guard

fn is_parsable_db_path(key: &object_store::path::Path) -> bool {
    key.parts().count() == EXPECTED_SEGMENTS && key.to_string().starts_with("databases/")
}

Try / catch

match DbPath::parse(key) {
    Err(PathError::InvalidFormat { expected, actual }) => {
        log::warn!("skipping non-conforming object {} (expected {}, got {})", key, expected, actual);
        continue; // or quarantine the object
    }
    r => r?,
}

Prevention

When it happens

Trigger: Parsing object-store keys (e.g. listing files and parsing each into a typed path struct) where a key has the wrong number of segments, wrong prefix, or wrong layout for the expected path type.

Common situations: Legacy or manually created files in the object store bucket; objects placed by a different InfluxDB version with changed path layouts; stray objects uploaded by tooling polluting the namespace.

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

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

Appendix: source

Thrown at influxdb3_write/src/paths.rs:15

use crate::YearMonth;
use chrono::prelude::*;
use influxdb3_id::{DbId, TableId, TableIndexId};
use influxdb3_wal::{SnapshotSequenceNumber, WalFileSequenceNumber};
use object_store::path::Path as ObjPath;
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";

View on GitHub (pinned to 06200ef96b)