influxdata/influxdb · critical · FormatError

invalid header

Error message

invalid header: {reason}

What it means

The catalog file header is internally inconsistent — for example a field documented as reserved is nonzero. The reader validates the header layout before trusting any records; a violation means the file was not produced by a compatible writer or its bytes were altered.

Solutions

1. Point the instance at the correct catalog directory (check config for the data/plugin paths).
2. Restore the catalog files from a backup produced by the same InfluxDB 3 version/format.
3. Do not modify or generate catalog files with custom scripts; use the supported restore commands.

Example fix

// before: influxdb3 serve --node-id=... --object-store=file --data-dir=/path/to/random/dir
// after: point at the real data dir containing the catalog
// influxdb3 serve --object-store=file --data-dir=/var/lib/influxdb3

// Confirm the data dir actually contains an InfluxDB 3 catalog before serving
if !data_dir.join("catalog").exists() {
    return Err(format!("{} does not look like an influxdb3 data dir", data_dir.display()));
}

if let Err(e) = catalog.open() {
    if e.to_string().contains("invalid header") {
        eprintln!("check --data-dir/--object-store config and file provenance");
    }
}

When it happens

Trigger: Opening a file that is not a valid catalog snapshot/log but was pointed at the catalog path; a header corrupted in its reserved/constant fields; a file written by incompatible or hand-crafted tooling.

Common situations: Misconfiguring the catalog directory to point at the wrong path (e.g. a data file or an unrelated format); restoring files from a different InfluxDB edition/format; corrupted disk blocks in the header page.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• {0}
• buffer too short: expected at least
• catalog format error
• header CRC32 mismatch: expected
• invalid magic bytes: expected

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

Appendix: source

Thrown at influxdb3_catalog/src/format/mod.rs:210

    UnknownNonUpgradeSafeRecord { record_id: u16 },

    /// Invalid record length.
    #[error("invalid record length: {length}")]
    InvalidRecordLength { length: u32 },

    /// Record data exceeds remaining file.
    #[error(
        "record data exceeds file bounds: offset {offset}, length {length}, file size {file_size}"
    )]
    RecordExceedsFile {
        offset: u64,
        length: u32,
        file_size: u64,
    },

    /// File header is internally inconsistent (e.g. a reserved field is
    /// nonzero).
    #[error("invalid header: {reason}")]
    InvalidHeader { reason: &'static str },

    /// A `RestoreCatalog` record was encountered during sync apply with an
    /// empty preload. Callers on a persistence path must first load the
    /// backup state off-lock via `preload_restore_for_records` /
    /// `preload_restore_for_file` and pass the resulting `RestorePreload`
    /// into the apply call.
    #[error(
        "RestoreCatalog record encountered without object-store access \
         (sync apply path): the catalog cannot reload backup state from \
         here — use the async apply path"
    )]
    RestoreRequiresStore,

    /// Loading the backup snapshot/log files referenced by a `RestoreCatalog`
    /// record failed.
    #[error("failed to load restore source: {0}")]
    RestoreLoadFailed(String),

View on GitHub (pinned to 06200ef96b)