{"record":{"id":"c199a2acbaec11f8","repo":"risingwavelabs/risingwave","slug":"legacy-checkpoint-missing-required-field-version","errorCode":null,"errorMessage":"legacy checkpoint missing required field `version`","messagePattern":"legacy checkpoint missing required field `version`","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/meta/src/hummock/manager/checkpoint.rs","lineNumber":176,"sourceCode":"            compressed_size = envelope.payload.len(),\n            decompressed_size = decompressed.len(),\n            compression_ratio =\n                format!(\"{:.2}x\", decompressed.len() as f64 / envelope.payload.len().max(1) as f64),\n            checksum = format!(\"{expected:#x}\"),\n            \"decoded compressed checkpoint\"\n        );\n        return Ok(ckpt);\n    }\n\n    // Legacy uncompressed format\n    tracing::info!(\n        data_size,\n        \"decoding checkpoint in legacy uncompressed format\"\n    );\n    let ckpt =\n        PbHummockVersionCheckpoint::decode(data).context(\"failed to decode legacy checkpoint\")?;\n    if ckpt.version.is_none() {\n        return Err(anyhow::anyhow!(\"legacy checkpoint missing required field `version`\").into());\n    }\n    Ok(ckpt)\n}\n\nfn decompress_payload(\n    algo: CheckpointCompressionAlgorithm,\n    payload: &[u8],\n) -> Result<std::borrow::Cow<'_, [u8]>> {\n    use anyhow::Context;\n\n    match algo {\n        CheckpointCompressionAlgorithm::CheckpointCompressionUnspecified => Ok(payload.into()),\n        CheckpointCompressionAlgorithm::CheckpointCompressionZstd => {\n            Ok(zstd::stream::decode_all(payload)\n                .map(std::borrow::Cow::Owned)\n                .context(\"zstd decompression failed\")?)\n        }\n        CheckpointCompressionAlgorithm::CheckpointCompressionLz4 => {","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/risingwavelabs/risingwave/blob/6469eb736d691e8e9b8a419a57edd6429ca77417/src/meta/src/hummock/manager/checkpoint.rs#L158-L194","documentation":"In the legacy (uncompressed, non-enveloped) checkpoint decode path, the PbHummockVersionCheckpoint must still carry a `version` field; its absence means the data predates any known checkpoint format and cannot be interpreted. decode_checkpoint_data fails fast instead of guessing the format.","triggerScenarios":"decode_checkpoint_data falls back to the legacy path (envelope decode failed), decodes raw bytes as PbHummockVersionCheckpoint, and finds ckpt.version == None.","commonSituations":"Reading checkpoint data written by a very old RisingWave release before versioning existed; corrupted bytes that happen to decode but lack version; hand-restored checkpoint objects from incompatible backups.","solutions":["Restore checkpoint data from a backup produced by a RisingWave version that writes the `version` field","Verify the object actually is a Hummock version checkpoint (not another protobuf type stored by mistake)","If the data is truly pre-versioning legacy state, re-bootstrap meta state instead of decoding it","Check for mixed-version deployment issues (old nodes writing checkpoints read by new nodes)"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Before trusting restored data, check it is a versioned checkpoint\nlet probe = PbHummockVersionCheckpoint::decode(bytes.as_ref())?;\nif probe.version.is_none() { /* treat as incompatible legacy data */ }\n","typeGuard":"fn is_legacy_unversioned(ckpt: &PbHummockVersionCheckpoint) -> bool { ckpt.version.is_none() }\n","tryCatchPattern":"match decode_checkpoint_data(bytes, size) {\n    Err(e) if e.to_string().contains(\"legacy checkpoint missing required field `version`\") => {\n        tracing::warn!(\"pre-versioning checkpoint data; re-bootstrap meta state\");\n        Err(e)\n    }\n    other => other,\n}\n","preventionTips":["Restore meta state only from backups of matching or newer versions","Verify object provenance before restoring checkpoint files","Plan migrations with explicit state re-bootstrap steps","Avoid mixed old/new writer clusters sharing one object store"],"tags":["rust","hummock","checkpoint","protobuf","compatibility"],"backgroundTag":"schema-validation-failed","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"}