{"record":{"id":"338cd83e1295b5d8","repo":"influxdata/influxdb","slug":"unknown-record-id-record-id-without-upgrade-safe-flag","errorCode":null,"errorMessage":"unknown record id {record_id} without UPGRADE_SAFE flag","messagePattern":"unknown record id (.+?) without UPGRADE_SAFE flag","errorType":"error_code","errorClass":"FormatError","httpStatus":null,"severity":"critical","filePath":"influxdb3_catalog/src/format/mod.rs","lineNumber":191,"sourceCode":"\n    /// Unsupported format version.\n    #[error(\"unsupported format version: {version}\")]\n    UnsupportedVersion { version: u32 },\n\n    /// Buffer too short for required data.\n    #[error(\"buffer too short: expected at least {expected} bytes, got {actual}\")]\n    BufferTooShort { expected: usize, actual: usize },\n\n    /// Header CRC32 checksum mismatch.\n    #[error(\"header CRC32 mismatch: expected {expected:#010x}, actual {actual:#010x}\")]\n    HeaderCrc32Mismatch { expected: u32, actual: u32 },\n\n    /// Payload CRC32 checksum mismatch.\n    #[error(\"payload CRC32 mismatch: expected {expected:#010x}, computed {computed:#010x}\")]\n    Crc32Mismatch { expected: u32, computed: u32 },\n\n    /// Unknown record type without UPGRADE_SAFE flag — hard error.\n    #[error(\"unknown record id {record_id} without UPGRADE_SAFE flag\")]\n    UnknownNonUpgradeSafeRecord { record_id: u16 },\n\n    /// Invalid record length.\n    #[error(\"invalid record length: {length}\")]\n    InvalidRecordLength { length: u32 },\n\n    /// Record data exceeds remaining file.\n    #[error(\n        \"record data exceeds file bounds: offset {offset}, length {length}, file size {file_size}\"\n    )]\n    RecordExceedsFile {\n        offset: u64,\n        length: u32,\n        file_size: u64,\n    },\n\n    /// File header is internally inconsistent (e.g. a reserved field is\n    /// nonzero).","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/format/mod.rs#L173-L209","documentation":"The catalog log reader encountered a record whose type id ({record_id}) is not recognized and does not carry the UPGRADE_SAFE flag. Unknown-but-upgrade-safe records may be skipped by older readers to allow forward compatibility; this record is not, so the reader treats it as a hard format error rather than silently skipping data. This guards against applying an incompletely-understood or corrupted record.","triggerScenarios":"Opening a catalog log written by a newer InfluxDB 3 version that introduced a non-upgrade-safe record type, or a corrupted record whose id bytes were mangled into an unknown value.","commonSituations":"Downgrading InfluxDB 3 to an older release against an existing catalog directory; mixed-version clusters sharing storage; corrupted WAL bytes.","solutions":["Upgrade the InfluxDB 3 binaries to the version that wrote the catalog (do not downgrade across catalog format changes).","If downgrade is required, export/restore data into a fresh catalog created by the older version.","Verify file integrity; a random corrupted id should also show other errors (CRC failures)."],"exampleFix":"// before: running influxdb3 3.x-old against a catalog written by 3.x-new\n// after: upgrade to matching/newer version\n// docker pull influxdb:3-latest  # instead of pinned older tag","handlingStrategy":"validation","validationCode":"// Check version compatibility before downgrade\nlet written_by = read_catalog_format_version(data_dir)?;\nif written_by > CURRENT_SUPPORTED_FORMAT_VERSION {\n    return Err(format!(\"catalog written by newer version {}; upgrade binaries\", written_by));\n}","typeGuard":null,"tryCatchPattern":"match open_catalog() {\n    Err(e) if e.to_string().contains(\"unknown record id\") => {\n        eprintln!(\"catalog written by a newer version; upgrade before retrying\");\n        Err(e)\n    }\n    r => r,\n}","preventionTips":["Never downgrade across catalog format changes without exporting/re-importing","Keep cluster nodes on the same InfluxDB 3 version","Test version changes against a copied data dir first"],"tags":["compatibility","versioning","catalog","forward-compatibility"],"backgroundTag":"invalid-enum-value","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"}