Hmbown/CodeWhale · error · std::io::Error

Checkpoint schema v is newer than supported v

Error message

Checkpoint schema v{session.schema_version} is newer than supported v{CURRENT_SESSION_SCHEMA_VERSION}

What it means

Raised when reading a saved checkpoint whose `schema_version` field exceeds `CURRENT_SESSION_SCHEMA_VERSION`. The session manager refuses to load files written by a newer build to avoid silently misinterpreting unknown fields. It is an `io::ErrorKind::InvalidData` error containing both the file's version and the maximum supported version.

Solutions

1. Upgrade to the build that wrote the checkpoint (one whose CURRENT_SESSION_SCHEMA_VERSION >= the reported version).
2. If the downgrade is intentional, start a fresh session instead of resuming.
3. As a last resort, hand-edit the checkpoint JSON's schema_version down only if you know the format did not actually change — risky and may drop data.

Example fix

// before
codewhale --resume session-abc   // error: schema v4 newer than supported v3
// after
cargo install codewhale --version 0.9
codewhale --resume session-abc

let v: serde_json::Value = serde_json::from_str(&content)?;
let schema = v["schema_version"].as_u64().unwrap_or(0);
if schema > CURRENT_SESSION_SCHEMA_VERSION { eprintln!("checkpoint too new: v{}", schema); }

match manager.load_checkpoint(path) {
    Err(e) if e.kind() == std::io::ErrorKind::InvalidData
        && e.to_string().contains("newer than supported") =>
    {
        // prompt user to upgrade or start a new session
    }
    other => other?,
}

When it happens

Trigger: Calling `load`/resume on a checkpoint JSON where `schema_version > CURRENT_SESSION_SCHEMA_VERSION`, typically after switching back from a newer build that already wrote checkpoints.

Common situations: Downgrading the codewhale binary after a session was saved by a newer release; switching branches locally; running an older pinned version on a shared machine.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Offline queue schema v
• Session goal schema v
• Session schema v is newer than supported v
• Cannot open session : its queued input is already open in…
• Offline queue schema v

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/b90a8df44c3f4652. Report an issue: GitHub.

Appendix: source

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

        let archive =
            archive_dir.join(source.file_name().ok_or_else(|| {
                io::Error::new(io::ErrorKind::InvalidInput, "invalid session path")
            })?);
        if !archive.exists() {
            write_atomic(&archive, &bytes)?;
        }
        Ok(())
    }

    fn read_checkpoint_file(&self, path: &Path) -> std::io::Result<Option<SavedSession>> {
        if !path.exists() {
            return Ok(None);
        }
        let content = fs::read_to_string(path)?;
        let mut session: SavedSession = serde_json::from_str(&content)
            .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
        if session.schema_version > CURRENT_SESSION_SCHEMA_VERSION {
            return Err(std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                format!(
                    "Checkpoint schema v{} is newer than supported v{}",
                    session.schema_version, CURRENT_SESSION_SCHEMA_VERSION
                ),
            ));
        }
        // A crash after retirement but before checkpoint removal must not
        // offer the deleted origin for recovery. Optional accounting damage
        // still permits recovery and is projected as incomplete below.
        if self
            .with_session_read_lock(&session.metadata.id, Self::late_usage_is_deleted)
            .unwrap_or(false)
        {
            return Ok(None);
        }
        session.system_prompt = strip_legacy_truncation_note(session.system_prompt);
        self.hydrate_approval_receipts(&mut session)?;

View on GitHub (pinned to 433685b202)