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

Checkpoint schema v{} is newer than supported v{}

Error message

Checkpoint schema v{} is newer than supported v{}

What it means

read_checkpoint_file() found a checkpoint JSON whose schema_version field is greater than the maximum this build supports. The reader deliberately fails closed instead of misinterpreting fields written by a newer Codewhale version; firing means the checkpoint was produced by newer software.

Source

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

        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
                ),
            ));
        }
        session.system_prompt = strip_legacy_truncation_note(session.system_prompt);
        self.hydrate_approval_receipts(&mut session)?;
        Ok(Some(session))
    }

    /// Load a specific session's crash-recovery checkpoint if present.
    pub fn load_session_checkpoint(
        &self,
        session_id: &str,
    ) -> std::io::Result<Option<SavedSession>> {
        let path = self.validated_checkpoint_path(session_id)?;

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Upgrade Codewhale to a version that supports the newer checkpoint schema
2. Restore the checkpoint from a backup written by a compatible version
3. Do not hand-edit the schema_version field down; unknown fields would be silently dropped

When it happens

Trigger: Thrown at crates/tui/src/session_manager.rs:1261 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/8fe47f0a22ef9853. Report an issue: GitHub.