Hmbown/CodeWhale · error · io::Error

unknown legacy checkpoint origin

Error message

unknown legacy checkpoint origin

What it means

To identify a legacy checkpoint's owning session, the manager reads only the first 1 MB of the file and parses top-level metadata via extract_top_level_metadata. If the session id cannot be extracted from that prefix, it returns InvalidData with "unknown legacy checkpoint origin" rather than reading an unbounded legacy transcript or following symlinks.

Solutions

1. Inspect the first 1 MB of the file for a top-level metadata object containing an id; repair or add it if the file was edited
2. Restore the legacy checkpoint from backup, or discard it and recreate the session
3. If the format is genuinely too old, migrate the file to a current checkpoint layout manually or via a migration tool

let mut prefix = Vec::new();
file.take(1024 * 1024).read_to_end(&mut prefix)?;
if extract_top_level_metadata(&prefix).is_none() {
    eprintln!("file has no recognizable metadata header; not a loadable legacy checkpoint");
}

match legacy_checkpoint_owner(path) {
    Ok(Some(id)) => adopt(id),
    Ok(None) | Err(_) => eprintln!("cannot determine owner; skipping this legacy checkpoint"),
}

When it happens

Trigger: Calling the legacy-checkpoint ownership probe on a file whose JSON header lacks a parseable top-level metadata block, or whose metadata sits beyond the first 1024*1024 bytes.

Common situations: A very old checkpoint format with no id in the header; a corrupted or hand-mangled legacy file; a huge legacy transcript whose metadata block was written after the 1 MB mark.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• 1
• Agent has no continuable checkpoint to resume from…
• Archive the legacy recording before accepting more…
• Cargo metadata dependencies for
• Checkpoint schema v is newer than supported v

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/022ff872b79f4b56. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/session_manager.rs:2097

    }

    fn legacy_checkpoint_origin(&self) -> io::Result<Option<String>> {
        use std::io::Read as _;

        let path = self.checkpoints_dir().join(LEGACY_CHECKPOINT_FILE);
        let file = match open_private_read_file(&path) {
            Ok(file) => file,
            Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(None),
            Err(error) => return Err(error),
        };
        // Lifecycle cleanup only needs the leading metadata. Never follow
        // links or read an unbounded legacy transcript to identify its owner.
        let mut prefix = Vec::new();
        file.take(1024 * 1024).read_to_end(&mut prefix)?;
        extract_top_level_metadata(&prefix)
            .map(|metadata| Some(metadata.id))
            .ok_or_else(|| {
                io::Error::new(
                    io::ErrorKind::InvalidData,
                    "unknown legacy checkpoint origin",
                )
            })
    }

    /// Clear one session's crash-recovery checkpoint. Scoped: this can never
    /// remove another session's checkpoint file or the legacy slot.
    pub fn clear_session_checkpoint(&self, session_id: &str) -> std::io::Result<()> {
        let path = self.validated_checkpoint_path(session_id)?;
        if path.exists() {
            fs::remove_file(path)?;
        }
        Ok(())
    }

    /// Remove the legacy single-slot checkpoint file.
    pub fn clear_legacy_checkpoint(&self) -> std::io::Result<()> {

View on GitHub (pinned to 73e0f67d83)