{"record":{"id":"d518131e66ea1dfb","repo":"xai-org/grok-build","slug":"unsupported-checkpoint-schema-version-schema-vers","errorCode":null,"errorMessage":"Unsupported checkpoint schema version {schema_version}. Cannot safely rewind past the compaction point.","messagePattern":"Unsupported checkpoint schema version (.+?)\\. Cannot safely rewind past the compaction point\\.","errorType":"error_code","errorClass":"io::Error","httpStatus":null,"severity":"error","filePath":"crates/codegen/xai-grok-shell/src/session/helpers/replay.rs","lineNumber":386,"sourceCode":"                    );\n                    return Err(io::Error::new(\n                        io::ErrorKind::InvalidData,\n                        format!(\n                            \"Compaction checkpoint file corrupt: {}. \\\n                             Cannot safely rewind past the compaction point.\",\n                            checkpoint_path.display()\n                        ),\n                    ));\n                }\n            };\n\n            if file.schema_version > 1 {\n                tracing::error!(\n                    schema_version = file.schema_version,\n                    path = %checkpoint_path.display(),\n                    \"Unsupported checkpoint schema version, cannot reconstruct conversation\"\n                );\n                return Err(io::Error::new(\n                    io::ErrorKind::InvalidData,\n                    format!(\n                        \"Unsupported checkpoint schema version {}. \\\n                         Cannot safely rewind past the compaction point.\",\n                        file.schema_version\n                    ),\n                ));\n            }\n\n            // Capture original_user_info from the checkpoint (even if we\n            // replace the conversation — it's needed by handle_rewind for\n            // the raw-updates prefix case).\n            if self.original_user_info.is_none() {\n                self.original_user_info = file.original_user_info.clone();\n            }\n\n            // Replace accumulated conversation with the compacted history.\n            self.conversation = file.compacted_history;","sourceCodeStart":368,"sourceCodeEnd":404,"githubUrl":"https://github.com/xai-org/grok-build/blob/bc7f02eddd3d84085849dc19ed216f11c23b0571/crates/codegen/xai-grok-shell/src/session/helpers/replay.rs#L368-L404","documentation":"The checkpoint file parsed successfully but its schema_version field is greater than 1, meaning it was written by a newer tool version whose format this binary does not understand. To avoid misinterpreting unknown fields, replay refuses to rewind past the compaction point, returning io::ErrorKind::InvalidData.","triggerScenarios":"handle_checkpoint (post-compaction branch) deserializes a CompactionCheckpointFile whose schema_version > 1, i.e. checkpoint produced by a newer release being replayed by an older binary.","commonSituations":"Downgrading the grok CLI after checkpoints were written by a newer version; sharing session directories between machines with different tool versions; switching release channels (stable vs preview).","solutions":["Upgrade the CLI to a version that supports checkpoint schema_version > 1","Rewind only to targets before the compaction point (raw-update replay path does not check the schema)","Back up, then remove/rename the newer checkpoint and accept conversation loss past compaction","Keep session directories pinned to a single tool version per machine"],"exampleFix":"// before: replaying v2 checkpoints with a binary that only knows v1\ngrok --version  # 0.9.x\n// after: upgrade so schema_version <= 1 is supported\ncargo install xai-grok-shell --locked  # or package-manager upgrade","handlingStrategy":"validation","validationCode":"let bytes = std::fs::read(&ckpt_path)?;\nlet v: serde_json::Value = serde_json::from_slice(&bytes)?;\nlet schema_version = v[\"schema_version\"].as_u64().unwrap_or(0);\nif schema_version > 1 {\n    eprintln!(\"checkpoint schema v{} requires a newer CLI; upgrade before rewinding past compaction\", schema_version);\n}","typeGuard":"fn schema_supported(bytes: &[u8]) -> bool {\n    serde_json::from_slice::<serde_json::Value>(bytes)\n        .ok()\n        .and_then(|v| v.get(\"schema_version\").and_then(|s| s.as_u64()))\n        .map(|v| v <= 1)\n        .unwrap_or(false)\n}","tryCatchPattern":"if let Err(e) = session.rewind(target) {\n    if e.kind() == io::ErrorKind::InvalidData && e.to_string().contains(\"schema version\") {\n        eprintln!(\"upgrade the CLI to replay this checkpoint\");\n        return Err(e.into());\n    }\n    return Err(e.into());\n}","preventionTips":["Keep the CLI version consistent across all machines sharing session data","Check schema_version in checkpoints before downgrading tools","Rewind to pre-compaction targets when stuck on an older binary","Pin releases with --locked installs to avoid accidental version drift"],"tags":["versioning","schema","compaction","compatibility"],"backgroundTag":"unsupported-schema-version","analyzedSha":"bc7f02eddd3d84085849dc19ed216f11c23b0571","analyzedAt":"2026-08-31T04:59:42.031Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}