influxdata/influxdb · critical · FormatError

unknown record id without UPGRADE_SAFE flag

Error message

unknown record id {record_id} without UPGRADE_SAFE flag

What it means

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.

Solutions

1. Upgrade the InfluxDB 3 binaries to the version that wrote the catalog (do not downgrade across catalog format changes).
2. If downgrade is required, export/restore data into a fresh catalog created by the older version.
3. Verify file integrity; a random corrupted id should also show other errors (CRC failures).

Example fix

// before: running influxdb3 3.x-old against a catalog written by 3.x-new
// after: upgrade to matching/newer version
// docker pull influxdb:3-latest  # instead of pinned older tag

// Check version compatibility before downgrade
let written_by = read_catalog_format_version(data_dir)?;
if written_by > CURRENT_SUPPORTED_FORMAT_VERSION {
    return Err(format!("catalog written by newer version {}; upgrade binaries", written_by));
}

match open_catalog() {
    Err(e) if e.to_string().contains("unknown record id") => {
        eprintln!("catalog written by a newer version; upgrade before retrying");
        Err(e)
    }
    r => r,
}

When it happens

Trigger: 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.

Common situations: Downgrading InfluxDB 3 to an older release against an existing catalog directory; mixed-version clusters sharing storage; corrupted WAL bytes.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unsupported format version
• failed to serialize record id
• {0}
• Adding a new database would exceed limit of
• attempted to create a resource that already exists

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

Appendix: source

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

    /// 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 },

    /// Unknown record type without UPGRADE_SAFE flag — hard error.
    #[error("unknown record id {record_id} without UPGRADE_SAFE flag")]
    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).

View on GitHub (pinned to 06200ef96b)