{"record":{"id":"c47ee0382bc5cb4c","repo":"risingwavelabs/risingwave","slug":"unsupported-metadata-snapshot-format-version-for-h","errorCode":null,"errorMessage":"unsupported metadata snapshot format version for hummock sequence partial decoding: {}","messagePattern":"unsupported metadata snapshot format version for hummock sequence partial decoding: (.+?)","errorType":"exception","errorClass":"BackupError","httpStatus":null,"severity":"error","filePath":"src/storage/backup/src/meta_snapshot_v2.rs","lineNumber":155,"sourceCode":"    };\n}\n\nfor_all_metadata_models_v2!(define_decode_metadata);\n\n// Metadata V2 is encoded as a positional list of sections. The actual encoded order inserts\n// `hummock_version` before `version_stats`, so `hummock_sequences` is section 26:\n// 0 seaql_migrations, 1 hummock_version, 2 version_stats, ..., 26 hummock_sequences.\n//\n// Keep this as a fixed index so partial decoding can skip directly to `hummock_sequences`.\nconst HUMMOCK_SEQUENCES_METADATA_SECTION_INDEX: usize = 26;\n\npub async fn decode_hummock_sequences_from_stream(\n    stream: MonitoredStreamingReader,\n) -> BackupResult<Vec<risingwave_meta_model::hummock_sequence::Model>> {\n    let mut reader = SnapshotPayloadReader::new(ObjectDataStreamReader::new(stream.into_stream()));\n    let (format_version, _snapshot_id) = reader.read_snapshot_header().await?;\n    if format_version < 2 {\n        return Err(BackupError::Other(anyhow!(\n            \"unsupported metadata snapshot format version for hummock sequence partial decoding: {}\",\n            format_version\n        )));\n    }\n    for _ in 0..HUMMOCK_SEQUENCES_METADATA_SECTION_INDEX {\n        skip_metadata_list(&mut reader).await?;\n    }\n    let hummock_sequences = read_n(&mut reader).await?;\n    reader.finish_after_skipping_to_end().await?;\n    Ok(hummock_sequences)\n}\n\nimpl Display for MetadataV2 {\n    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {\n        writeln!(f, \"clusters: {:#?}\", self.clusters)?;\n        writeln!(\n            f,\n            \"Hummock version: id {}, committed_epoch: {:?}\",","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/risingwavelabs/risingwave/blob/6469eb736d691e8e9b8a419a57edd6429ca77417/src/storage/backup/src/meta_snapshot_v2.rs#L137-L173","documentation":"decode_hummock_sequences_from_stream reads the snapshot header and requires format_version >= 2 to partially decode hummock sequences; older snapshots throw \"unsupported metadata snapshot format version for hummock sequence partial decoding: {}\". The partial (streaming) decoder only understands the V2 section layout.","triggerScenarios":"Calling decode_hummock_sequences_from_stream (directly or via load on a MetaSnapshot decoded as V2) on a snapshot whose header reports format_version 0 or 1.","commonSituations":"Restoring/inspecting a backup created by an old RisingWave version (pre-V2 snapshot format) with a current binary path that expects V2; a backup taken before the V2 migration; automated tooling assuming all snapshots are V2.","solutions":["Use MetaSnapshotV1 (full decode) for snapshots with format_version < 2 and read hummock sequences from the fully decoded model.","Re-create the backup on a current RisingWave version so the snapshot is written in V2 format, then retry.","Dispatch on the header format_version before choosing the decoder instead of assuming V2.","If this hits during cluster upgrade, complete the meta store migration to V2 before taking new snapshots."],"exampleFix":"// before: always partial V2 decode\nlet seqs = decode_hummock_sequences_from_stream(stream).await?;\n// after: branch on version\nlet (version, _) = read_header(&stream).await?;\nlet seqs = if version >= 2 {\n    decode_hummock_sequences_from_stream(stream).await?\n} else {\n    MetaSnapshotV1::decode(stream)?.hummock_sequences\n};","handlingStrategy":"fallback","validationCode":"// read header first and dispatch\nlet (format_version, _) = read_snapshot_header(&stream).await?;\nif format_version < 2 { /* use full V1 decode path instead */ }","typeGuard":"fn supports_partial_decode(format_version: u32) -> bool { format_version >= 2 }","tryCatchPattern":"match decode_hummock_sequences_from_stream(stream).await {\n    Ok(seqs) => seqs,\n    Err(e) if e.to_string().contains(\"unsupported metadata snapshot format version\") => {\n        log::info!(\"legacy snapshot; using full decode path\");\n        decode_v1_full(stream).await?\n    }\n    Err(e) => return Err(e.into()),\n}","preventionTips":["Check the snapshot header format_version before choosing a decoder.","Recreate old backups on a current RisingWave version to get V2 snapshots.","Keep at least one binary version capable of reading each historical snapshot format."],"tags":["rust","backup","version-compatibility","snapshot-format"],"backgroundTag":"unsupported-operation","analyzedSha":"6469eb736d691e8e9b8a419a57edd6429ca77417","analyzedAt":"2026-09-11T21:06:21.487Z","contentChangedAt":"2026-09-11T21:06:21.487Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}