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

Session schema v is newer than supported v

Error message

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

What it means

SavedSession files carry a schema_version, and the loader refuses to open a session whose stored version is greater than CURRENT_SESSION_SCHEMA_VERSION. This is a forward-compatibility guard: a newer CodeWhale (or another tool) wrote the file with fields this build does not understand, so loading it could silently corrupt or misinterpret data. The error surfaces as an io::Error with ErrorKind::InvalidData from session loading.

Solutions

1. Upgrade CodeWhale to a build whose CURRENT_SESSION_SCHEMA_VERSION is >= the session file's schema_version.
2. Edit the session JSON in ~/.codewhale/sessions and set schema_version down to the supported value only if you have verified no new fields are present.
3. Delete or archive the incompatible session file if its history is not needed.

Example fix

// before: downgraded binary, fails to load session
// after: upgrade to the newer release that supports the schema
 cargo install codewhale  # or: git pull && cargo build --release -p codewhale-tui

let v: serde_json::Value = serde_json::from_str(&fs::read_to_string(&path)?)?;
if v["schema_version"].as_u64().unwrap_or(0) > CURRENT_SESSION_SCHEMA_VERSION {
    // refuse or upgrade path
}

fn is_supported_schema(s: &SavedSession) -> bool { s.schema_version <= CURRENT_SESSION_SCHEMA_VERSION }

match load_session(id) {
    Err(e) if e.kind() == io::ErrorKind::InvalidData && e.to_string().contains("newer than supported") => upgrade_codewhale(),
    other => other?,
}

When it happens

Trigger: Loading a session via session_manager (e.g. load/open by id) where session.schema_version > CURRENT_SESSION_SCHEMA_VERSION after serde_json::from_str succeeds.

Common situations: Downgrading CodeWhale after a schema bump; sharing session files from a newer machine/build; restoring backups written by a newer release.

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

• Checkpoint schema v is newer than supported v
• Offline queue schema v
• Offline queue schema v
• Session goal schema v
• Session schema v is newer than supported v

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

Appendix: source

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

            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
            Err(error) => return Err(error),
        }
        Ok(Some(state))
    }

    /// Read a session snapshot without repairing tool call/result pairs.
    ///
    /// This is the correct API for embedding hosts that inspect or update a
    /// durable session while an engine may still be executing a tool call.
    /// A dangling `tool_use` is not proof of a crashed process in that state.
    pub fn load_session_snapshot(&self, id: &str) -> std::io::Result<SavedSession> {
        let path = self.validated_session_path(id)?;

        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!(
                    "Session schema v{} is newer than supported v{}",
                    session.schema_version, CURRENT_SESSION_SCHEMA_VERSION
                ),
            ));
        }

        session.system_prompt = strip_legacy_truncation_note(session.system_prompt);
        session.ensure_journal();
        self.hydrate_approval_receipts(&mut session)?;
        self.apply_late_usage_to_metadata(&mut session.metadata);

        Ok(session)
    }

    /// Load and repair a session after a known process or engine restart.
    ///

View on GitHub (pinned to 433685b202)