{"record":{"id":"b90a8df44c3f4652","repo":"Hmbown/CodeWhale","slug":"checkpoint-schema-v-session-schema-version-is-newer-than","errorCode":null,"errorMessage":"Checkpoint schema v{session.schema_version} is newer than supported v{CURRENT_SESSION_SCHEMA_VERSION}","messagePattern":"Checkpoint 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":1964,"sourceCode":"        let archive =\n            archive_dir.join(source.file_name().ok_or_else(|| {\n                io::Error::new(io::ErrorKind::InvalidInput, \"invalid session path\")\n            })?);\n        if !archive.exists() {\n            write_atomic(&archive, &bytes)?;\n        }\n        Ok(())\n    }\n\n    fn read_checkpoint_file(&self, path: &Path) -> std::io::Result<Option<SavedSession>> {\n        if !path.exists() {\n            return Ok(None);\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                    \"Checkpoint schema v{} is newer than supported v{}\",\n                    session.schema_version, CURRENT_SESSION_SCHEMA_VERSION\n                ),\n            ));\n        }\n        // A crash after retirement but before checkpoint removal must not\n        // offer the deleted origin for recovery. Optional accounting damage\n        // still permits recovery and is projected as incomplete below.\n        if self\n            .with_session_read_lock(&session.metadata.id, Self::late_usage_is_deleted)\n            .unwrap_or(false)\n        {\n            return Ok(None);\n        }\n        session.system_prompt = strip_legacy_truncation_note(session.system_prompt);\n        self.hydrate_approval_receipts(&mut session)?;","sourceCodeStart":1946,"sourceCodeEnd":1982,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/433685b2024e7bc4c99e1e2e326bcad39b4d9d65/crates/tui/src/session_manager.rs#L1946-L1982","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade to the build that wrote the checkpoint (one whose CURRENT_SESSION_SCHEMA_VERSION >= the reported version).","If the downgrade is intentional, start a fresh session instead of resuming.","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."],"exampleFix":"// before\ncodewhale --resume session-abc   // error: schema v4 newer than supported v3\n// after\ncargo install codewhale --version 0.9\ncodewhale --resume session-abc","handlingStrategy":"try-catch","validationCode":"let v: serde_json::Value = serde_json::from_str(&content)?;\nlet schema = v[\"schema_version\"].as_u64().unwrap_or(0);\nif schema > CURRENT_SESSION_SCHEMA_VERSION { eprintln!(\"checkpoint too new: v{}\", schema); }","typeGuard":null,"tryCatchPattern":"match manager.load_checkpoint(path) {\n    Err(e) if e.kind() == std::io::ErrorKind::InvalidData\n        && e.to_string().contains(\"newer than supported\") =>\n    {\n        // prompt user to upgrade or start a new session\n    }\n    other => other?,\n}","preventionTips":["Pin/upgrade your binary version to match where the checkpoint was written.","Before downgrading, start a fresh session.","Check the checkpoint's schema_version before attempting resume."],"tags":["io","schema-version","session","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"}