influxdata/influxdb · critical · CatalogError

catalog format error

Error message

catalog format error: {0}

What it means

CatalogError::Format wraps a FormatError indicating the persisted catalog data could not be parsed or its serialized form was malformed. The library throws it when deserializing catalog snapshots/WAL data and the bytes do not match the expected schema or version. It usually means the stored catalog is corrupt or written by an incompatible version.

Solutions

1. Restore the catalog from a known-good backup/snapshot
2. Check the catalog format version written vs the reader version and use a matching influxdb3 release
3. Inspect the FormatError details to find the malformed record
4. Never hand-edit persisted catalog files; regenerate via supported tooling

Example fix

// before: reading catalog written by newer schema
// influxdb3 3.0 binary against 3.1 catalog format
// after: upgrade binary
// influxdb3 serve --object-store file --data-dir <dir>  # use binary matching catalog format version

// Pin the influxdb3 version that matches the stored catalog format
assert_eq!(catalog_format_version_on_disk(), crate::catalog::FORMAT_VERSION);

match result {
    Err(CatalogError::Format(e)) => {
        // stop startup; alert operator to restore from backup
        return Err(anyhow!("catalog data unreadable, restore from backup: {e}"));
    }
    _ => {}
}

When it happens

Trigger: Loading a catalog checkpoint or serialized node/resource definition whose JSON/protobuf payload fails to deserialize; reading catalog files written by a different influxdb3 schema version; manual edits or truncation of catalog storage.

Common situations: Upgrading/downgrading InfluxDB 3 across incompatible catalog schema versions; corrupted files in the object store; hand-edited catalog data; partial write from a crashed process.

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
• crc32 checksum mismatch
• failed to serialize record id
• header CRC32 mismatch: expected

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:47

    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.inner())
    }
}

use crate::{
    channel::SubscriptionError, format::FeatureLevel, format::FormatError,
    log::versions::v4::StorageMode, object_store::ObjectStoreCatalogError,
};

#[derive(Debug, thiserror::Error)]
pub enum CatalogError {
    #[error(transparent)]
    Enterprise(#[from] EnterpriseCatalogError),

    #[error("object store error: {0:?}")]
    ObjectStore(#[from] ObjectStoreCatalogError),

    #[error("catalog format error: {0}")]
    Format(#[from] FormatError),

    #[error("attempted to create a resource that already exists")]
    AlreadyExists,

    #[error("the requested resource was not found: {0}")]
    NotFound(String),

    #[error("attempted to modify resource that was already deleted: {0}")]
    AlreadyDeleted(String),

    /// Request is idempotent: no catalog state would change.
    #[error("no catalog changes to apply: {details}")]
    NoCatalogChange { details: String },

    /// Request is invalid.
    #[error("catalog internal error: {details}")]
    Internal { details: String },

View on GitHub (pinned to 06200ef96b)