influxdata/influxdb · critical · FormatError

invalid magic bytes: expected

Error message

invalid magic bytes: expected {expected:?}, got {actual:?}

What it means

`FormatError::InvalidMagic` is returned when the first 4 bytes of a catalog format file do not match the expected magic bytes. The library uses magic bytes to confirm a file is a valid catalog format file before parsing; mismatch means the file is not a catalog file or is corrupted.

Solutions

1. Verify the file path configuration points at the actual catalog file
2. Check whether the file is truncated/corrupted (compare size and first bytes) and restore from backup
3. Confirm the file was produced by the same influxdb3 catalog format, not another component

let mut hdr = [0u8; 4];
File::open(&path)?.read_exact(&mut hdr)?;
if hdr != EXPECTED_MAGIC {
    return Err(format!("{path:?} is not a catalog file (magic {hdr:?})"));
}

match result {
    Err(FormatError::InvalidMagic { expected, actual }) => {
        log::error!("bad catalog file: expected {expected:?}, got {actual:?}");
        // fall back to backup
    }
    r => r?,
}

When it happens

Trigger: Opening/reading a catalog file whose header does not begin with the expected 4-byte magic; pointing the catalog at a wrong or empty file.

Common situations: Misconfigured object-store/file path pointing at the wrong file; truncated or zero-filled files after disk failure; files produced by a different tool or format.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

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

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

Appendix: source

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

    pub const fn none() -> Self {
        Self(Self::NONE)
    }

    /// Create flags with UPGRADE_SAFE set.
    pub const fn upgrade_safe() -> Self {
        Self(Self::UPGRADE_SAFE)
    }
}

/// Errors that can occur when working with the binary format.
#[derive(Debug, Clone, thiserror::Error)]
pub enum FormatError {
    /// A decoded record failed to apply to the catalog.
    #[error(transparent)]
    Apply(#[from] apply::ApplyError),

    /// Invalid magic bytes at start of file.
    #[error("invalid magic bytes: expected {expected:?}, got {actual:?}")]
    InvalidMagic { expected: [u8; 4], actual: [u8; 4] },

    /// Unsupported format version.
    #[error("unsupported format version: {version}")]
    UnsupportedVersion { version: u32 },

    /// Buffer too short for required data.
    #[error("buffer too short: expected at least {expected} bytes, got {actual}")]
    BufferTooShort { expected: usize, actual: usize },

    /// Header CRC32 checksum mismatch.
    #[error("header CRC32 mismatch: expected {expected:#010x}, actual {actual:#010x}")]
    HeaderCrc32Mismatch { expected: u32, actual: u32 },

    /// Payload CRC32 checksum mismatch.
    #[error("payload CRC32 mismatch: expected {expected:#010x}, computed {computed:#010x}")]
    Crc32Mismatch { expected: u32, computed: u32 },

View on GitHub (pinned to 06200ef96b)