{"record":{"id":"a89b03bb6729f73e","repo":"Hmbown/CodeWhale","slug":"item-schema-v-is-newer-than-supported-v","errorCode":null,"errorMessage":"Item schema v{} is newer than supported v{}","messagePattern":"Item schema v(.+?) is newer than supported v(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/tui/src/runtime_threads.rs","lineNumber":1325,"sourceCode":"            .with_context(|| format!(\"Failed to parse turn {}\", path.display()))?;\n        if record.schema_version > CURRENT_RUNTIME_SCHEMA_VERSION {\n            bail!(\n                \"Turn schema v{} is newer than supported v{}\",\n                record.schema_version,\n                CURRENT_RUNTIME_SCHEMA_VERSION\n            );\n        }\n        Ok(record)\n    }\n\n    pub fn load_item(&self, item_id: &str) -> Result<TurnItemRecord> {\n        let path = self.item_path(item_id)?;\n        let raw = read_store_file(&path)\n            .with_context(|| format!(\"Failed to read item {}\", path.display()))?;\n        let record: TurnItemRecord = serde_json::from_str(&raw)\n            .with_context(|| format!(\"Failed to parse item {}\", path.display()))?;\n        if record.schema_version > CURRENT_RUNTIME_SCHEMA_VERSION {\n            bail!(\n                \"Item schema v{} is newer than supported v{}\",\n                record.schema_version,\n                CURRENT_RUNTIME_SCHEMA_VERSION\n            );\n        }\n        Ok(record)\n    }\n\n    pub fn list_threads(&self) -> Result<Vec<ThreadRecord>> {\n        let mut out = Vec::new();\n        let threads_dir = checked_existing_runtime_store_dir(&self.threads_dir)?;\n        for entry in fs::read_dir(&threads_dir)\n            .with_context(|| format!(\"Failed to read {}\", threads_dir.display()))?\n        {\n            let entry = entry?;\n            let path = entry.path();\n            if path.extension().is_none_or(|ext| ext != \"json\") {\n                continue;","sourceCodeStart":1307,"sourceCodeEnd":1343,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/0c42157ee52f9d55af2b506d71b46249910f77d3/crates/tui/src/runtime_threads.rs#L1307-L1343","documentation":"load_item guards turn item records the same way: an item JSON with schema_version greater than CURRENT_RUNTIME_SCHEMA_VERSION (2) is rejected with 'Item schema vN is newer than supported v2'. Items are the leaf records of the thread/turn/item hierarchy and the check prevents reading item shapes this build does not understand.","triggerScenarios":"Calling RuntimeThreadStore::load_item(item_id) against a store written by a newer Codewhale build (schema_version > 2).","commonSituations":"Mixed-version installs sharing one data dir; rollback scenarios; opening archives produced by a newer release.","solutions":["Upgrade Codewhale to a build that supports the item schema version reported in the message.","Start with a clean data directory if the old items are not needed.","Keep per-version data dirs (or migrate forward only) to avoid mixing schema versions."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Rust: preflight the item file's schema version before load_item\nlet path = store.item_path(item_id)?;\nif let Ok(raw) = std::fs::read_to_string(&path) {\n    if let Ok(v) = serde_json::from_str::<serde_json::Value>(&raw) {\n        if v.get(\"schema_version\").and_then(|s| s.as_u64()).unwrap_or(0) > 2 {\n            anyhow::bail!(\"item {item_id} uses a newer schema; upgrade Codewhale first\");\n        }\n    }\n}\nlet item = store.load_item(item_id)?;","typeGuard":null,"tryCatchPattern":"// Rust: classify version-incompatibility errors for a targeted upgrade message\nmatch store.load_item(item_id) {\n    Ok(item) => Ok(item),\n    Err(err) if err.to_string().contains(\"newer than supported\") => {\n        Err(anyhow::anyhow!(\"item store is from a newer Codewhale; upgrade: {err}\"))\n    }\n    Err(err) => Err(err),\n}","preventionTips":["Do not mix Codewhale versions over one data directory.","Check schema_version in item JSON before importing external records.","Prefer a clean data dir after downgrades rather than partial reads."],"tags":["schema","versioning","persistence","thread-store","rust"],"backgroundTag":"schema-version-mismatch","analyzedSha":"0c42157ee52f9d55af2b506d71b46249910f77d3","analyzedAt":"2026-08-20T21:50:45.477Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}