{"record":{"id":"7eb3bfeb10a12283","repo":"influxdata/influxdb","slug":"catalog-format-error-0","errorCode":null,"errorMessage":"catalog format error: {0}","messagePattern":"catalog format error: (.+?)","errorType":"error_code","errorClass":"CatalogError","httpStatus":null,"severity":"critical","filePath":"influxdb3_catalog/src/error.rs","lineNumber":47,"sourceCode":"    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {\n        write!(f, \"{}\", self.inner())\n    }\n}\n\nuse crate::{\n    channel::SubscriptionError, format::FeatureLevel, format::FormatError,\n    log::versions::v4::StorageMode, object_store::ObjectStoreCatalogError,\n};\n\n#[derive(Debug, thiserror::Error)]\npub enum CatalogError {\n    #[error(transparent)]\n    Enterprise(#[from] EnterpriseCatalogError),\n\n    #[error(\"object store error: {0:?}\")]\n    ObjectStore(#[from] ObjectStoreCatalogError),\n\n    #[error(\"catalog format error: {0}\")]\n    Format(#[from] FormatError),\n\n    #[error(\"attempted to create a resource that already exists\")]\n    AlreadyExists,\n\n    #[error(\"the requested resource was not found: {0}\")]\n    NotFound(String),\n\n    #[error(\"attempted to modify resource that was already deleted: {0}\")]\n    AlreadyDeleted(String),\n\n    /// Request is idempotent: no catalog state would change.\n    #[error(\"no catalog changes to apply: {details}\")]\n    NoCatalogChange { details: String },\n\n    /// Request is invalid.\n    #[error(\"catalog internal error: {details}\")]\n    Internal { details: String },","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/error.rs#L29-L65","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Restore the catalog from a known-good backup/snapshot","Check the catalog format version written vs the reader version and use a matching influxdb3 release","Inspect the FormatError details to find the malformed record","Never hand-edit persisted catalog files; regenerate via supported tooling"],"exampleFix":"// before: reading catalog written by newer schema\n// influxdb3 3.0 binary against 3.1 catalog format\n// after: upgrade binary\n// influxdb3 serve --object-store file --data-dir <dir>  # use binary matching catalog format version","handlingStrategy":"validation","validationCode":"// Pin the influxdb3 version that matches the stored catalog format\nassert_eq!(catalog_format_version_on_disk(), crate::catalog::FORMAT_VERSION);","typeGuard":null,"tryCatchPattern":"match result {\n    Err(CatalogError::Format(e)) => {\n        // stop startup; alert operator to restore from backup\n        return Err(anyhow!(\"catalog data unreadable, restore from backup: {e}\"));\n    }\n    _ => {}\n}","preventionTips":["Never hand-edit persisted catalog files","Take snapshots before version upgrades","Keep influxdb3 binaries and stored formats in lockstep","Monitor for truncated writes after crashes"],"tags":["serialization","catalog","corruption"],"backgroundTag":"schema-validation-failed","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}