{"record":{"id":"5622d3b550c1e2d3","repo":"Hmbown/CodeWhale","slug":"session-schema-v-session-schema-version-is-newer-than","errorCode":null,"errorMessage":"Session schema v{session.schema_version} is newer than supported v{CURRENT_SESSION_SCHEMA_VERSION}","messagePattern":"Session schema v(.+?) is newer than supported v(.+?)","errorType":"exception","errorClass":"std::io::Error","httpStatus":null,"severity":"error","filePath":"crates/tui/src/session_manager.rs","lineNumber":2274,"sourceCode":"            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}\n            Err(error) => return Err(error),\n        }\n        Ok(Some(state))\n    }\n\n    /// Read a session snapshot without repairing tool call/result pairs.\n    ///\n    /// This is the correct API for embedding hosts that inspect or update a\n    /// durable session while an engine may still be executing a tool call.\n    /// A dangling `tool_use` is not proof of a crashed process in that state.\n    pub fn load_session_snapshot(&self, id: &str) -> std::io::Result<SavedSession> {\n        let path = self.validated_session_path(id)?;\n\n        let content = fs::read_to_string(&path)?;\n        let mut session: SavedSession = serde_json::from_str(&content)\n            .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;\n        if session.schema_version > CURRENT_SESSION_SCHEMA_VERSION {\n            return Err(std::io::Error::new(\n                std::io::ErrorKind::InvalidData,\n                format!(\n                    \"Session schema v{} is newer than supported v{}\",\n                    session.schema_version, CURRENT_SESSION_SCHEMA_VERSION\n                ),\n            ));\n        }\n\n        session.system_prompt = strip_legacy_truncation_note(session.system_prompt);\n        session.ensure_journal();\n        self.hydrate_approval_receipts(&mut session)?;\n        self.apply_late_usage_to_metadata(&mut session.metadata);\n\n        Ok(session)\n    }\n\n    /// Load and repair a session after a known process or engine restart.\n    ///","sourceCodeStart":2256,"sourceCodeEnd":2292,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/433685b2024e7bc4c99e1e2e326bcad39b4d9d65/crates/tui/src/session_manager.rs#L2256-L2292","documentation":"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.","triggerScenarios":"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.","commonSituations":"Downgrading CodeWhale after a schema bump; sharing session files from a newer machine/build; restoring backups written by a newer release.","solutions":["Upgrade CodeWhale to a build whose CURRENT_SESSION_SCHEMA_VERSION is >= the session file's schema_version.","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.","Delete or archive the incompatible session file if its history is not needed."],"exampleFix":"// before: downgraded binary, fails to load session\n// after: upgrade to the newer release that supports the schema\n cargo install codewhale  # or: git pull && cargo build --release -p codewhale-tui","handlingStrategy":"validation","validationCode":"let v: serde_json::Value = serde_json::from_str(&fs::read_to_string(&path)?)?;\nif v[\"schema_version\"].as_u64().unwrap_or(0) > CURRENT_SESSION_SCHEMA_VERSION {\n    // refuse or upgrade path\n}","typeGuard":"fn is_supported_schema(s: &SavedSession) -> bool { s.schema_version <= CURRENT_SESSION_SCHEMA_VERSION }","tryCatchPattern":"match load_session(id) {\n    Err(e) if e.kind() == io::ErrorKind::InvalidData && e.to_string().contains(\"newer than supported\") => upgrade_codewhale(),\n    other => other?,\n}","preventionTips":["Keep all CodeWhale installs on the same or newer schema version","Before downgrading, export or archive sessions","Check release notes for schema bumps before sharing session files across machines"],"tags":["session","schema-version","forward-compatibility"],"backgroundTag":"schema-validation-failed","analyzedSha":"433685b2024e7bc4c99e1e2e326bcad39b4d9d65","analyzedAt":"2026-09-15T12:24:24.634Z","contentChangedAt":"2026-09-15T12:24:24.634Z","schemaVersion":2},"datasetVersion":"2026-09-22T06:17:15.046Z"}