xai-org/grok-build · error · io::Error

Unsupported checkpoint schema version {schema_version}. Cann

Error message

Unsupported checkpoint schema version {schema_version}. Cannot safely rewind past the compaction point.

What it means

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.

Source

Thrown at crates/codegen/xai-grok-shell/src/session/helpers/replay.rs:386

                    );
                    return Err(io::Error::new(
                        io::ErrorKind::InvalidData,
                        format!(
                            "Compaction checkpoint file corrupt: {}. \
                             Cannot safely rewind past the compaction point.",
                            checkpoint_path.display()
                        ),
                    ));
                }
            };

            if file.schema_version > 1 {
                tracing::error!(
                    schema_version = file.schema_version,
                    path = %checkpoint_path.display(),
                    "Unsupported checkpoint schema version, cannot reconstruct conversation"
                );
                return Err(io::Error::new(
                    io::ErrorKind::InvalidData,
                    format!(
                        "Unsupported checkpoint schema version {}. \
                         Cannot safely rewind past the compaction point.",
                        file.schema_version
                    ),
                ));
            }

            // Capture original_user_info from the checkpoint (even if we
            // replace the conversation — it's needed by handle_rewind for
            // the raw-updates prefix case).
            if self.original_user_info.is_none() {
                self.original_user_info = file.original_user_info.clone();
            }

            // Replace accumulated conversation with the compacted history.
            self.conversation = file.compacted_history;

View on GitHub (pinned to bc7f02eddd)

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

Example fix

// before: replaying v2 checkpoints with a binary that only knows v1
grok --version  # 0.9.x
// after: upgrade so schema_version <= 1 is supported
cargo install xai-grok-shell --locked  # or package-manager upgrade

Defensive patterns

Strategy: validation

Validate before calling

let bytes = std::fs::read(&ckpt_path)?;
let v: serde_json::Value = serde_json::from_slice(&bytes)?;
let schema_version = v["schema_version"].as_u64().unwrap_or(0);
if schema_version > 1 {
    eprintln!("checkpoint schema v{} requires a newer CLI; upgrade before rewinding past compaction", schema_version);
}

Type guard

fn schema_supported(bytes: &[u8]) -> bool {
    serde_json::from_slice::<serde_json::Value>(bytes)
        .ok()
        .and_then(|v| v.get("schema_version").and_then(|s| s.as_u64()))
        .map(|v| v <= 1)
        .unwrap_or(false)
}

Try / catch

if let Err(e) = session.rewind(target) {
    if e.kind() == io::ErrorKind::InvalidData && e.to_string().contains("schema version") {
        eprintln!("upgrade the CLI to replay this checkpoint");
        return Err(e.into());
    }
    return Err(e.into());
}

Prevention

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

When it happens

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

Common situations: 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).

Related errors

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/d518131e66ea1dfb. Report an issue: GitHub.