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

Compaction checkpoint file missing

Error message

Compaction checkpoint file missing: {checkpoint_path}. Cannot safely rewind past the compaction point.

What it means

During session replay, when the rewind target is before a compaction point, the replayer must read the compaction checkpoint JSON file to restore the original user_info that the model saw pre-compaction. This io::ErrorKind::NotFound is thrown when the checkpoint file referenced by the compaction record does not exist on disk. Rewinding past that compaction point is unsafe without it, so replay aborts.

Solutions

Restore or re-copy the missing checkpoint file named in the message into the session directory
Restore the session directory from backup
Rewind to a target at or after the compaction point instead of before it
Discard the corrupted/lossy session and start a new one

Example fix

// before: rewinding past compaction with a pruned session dir
session.rewind(early_target)?;
// after: verify checkpoint exists first
let ckpt = session_dir.join(&info.checkpoint_file);
anyhow::ensure!(ckpt.exists(), "checkpoint missing: {}", ckpt.display());
session.rewind(early_target)?;

Defensive patterns

Strategy: validation

Validate before calling

let ckpt_path = session_dir.join(&info.checkpoint_file);
if !ckpt_path.exists() {
    return Err(anyhow!("checkpoint missing, cannot rewind past compaction: {}", ckpt_path.display()));
}

Try / catch

match rewind_result {
    Err(e) if e.kind() == io::ErrorKind::NotFound && e.to_string().contains("checkpoint") => restore_from_backup_or_rewind_after_compaction(),
    Err(e) => return Err(e.into()),
    Ok(()) => {}
}

Prevention

Never manually delete files inside session directories
Exclude checkpoint files from cleanup scripts and sync ignore rules
Copy/rsync session directories with checksums to ensure completeness
Back up session dirs before attempting rewinds

When it happens

Trigger: Calling rewind/process_update on a session whose update log contains an XaiSessionUpdate::CompactionCheckpoint with target < prompt_index_at_compaction, while session_dir/checkpoint_file has been deleted or never written.

Common situations: User manually cleaned the session directory or ran a cleanup/pruning script; checkpoint write was interrupted by crash or power loss; session directory moved or copied incompletely between machines; older tool version wrote compaction records before checkpoint files were introduced.

Related errors

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

Appendix: source

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

        info: &CompactionCheckpointInfo,
        session_dir: &Path,
    ) -> io::Result<ReplayAction> {
        if self.target < info.prompt_index_at_compaction {
            // Target is before this compaction — don't load the compacted
            // history (we'll reconstruct from raw updates). But the
            // checkpoint is still required for original_user_info — the
            // historical User(user_info) that the model saw for these
            // pre-compaction turns. Without it we'd use the post-compaction
            // rebuilt user_info, which is wrong data.
            let checkpoint_path = session_dir.join(&info.checkpoint_file);
            let bytes = match std::fs::read(&checkpoint_path) {
                Ok(b) => b,
                Err(e) if e.kind() == io::ErrorKind::NotFound => {
                    tracing::error!(
                        path = %checkpoint_path.display(),
                        "Compaction checkpoint file missing, cannot restore original user_info"
                    );
                    return Err(io::Error::new(
                        io::ErrorKind::NotFound,
                        format!(
                            "Compaction checkpoint file missing: {}. \
                             Cannot safely rewind past the compaction point.",
                            checkpoint_path.display()
                        ),
                    ));
                }
                Err(e) => return Err(e),
            };
            match serde_json::from_slice::<CompactionCheckpointFile>(&bytes) {
                Ok(file) => {
                    if self.original_user_info.is_none() {
                        self.original_user_info = file.original_user_info;
                    }
                }
                Err(e) => {
                    tracing::error!(

View on GitHub (pinned to bc7f02eddd)