What causes "Item schema v{} is newer than supported v{}" in Hmbown/CodeWhale?

Upgrade Codewhale to a build that supports the item schema version reported in the message.

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

Error message

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

What it means

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.

Source

Thrown at crates/tui/src/runtime_threads.rs:1325

            .with_context(|| format!("Failed to parse turn {}", path.display()))?;
        if record.schema_version > CURRENT_RUNTIME_SCHEMA_VERSION {
            bail!(
                "Turn schema v{} is newer than supported v{}",
                record.schema_version,
                CURRENT_RUNTIME_SCHEMA_VERSION
            );
        }
        Ok(record)
    }

    pub fn load_item(&self, item_id: &str) -> Result<TurnItemRecord> {
        let path = self.item_path(item_id)?;
        let raw = read_store_file(&path)
            .with_context(|| format!("Failed to read item {}", path.display()))?;
        let record: TurnItemRecord = serde_json::from_str(&raw)
            .with_context(|| format!("Failed to parse item {}", path.display()))?;
        if record.schema_version > CURRENT_RUNTIME_SCHEMA_VERSION {
            bail!(
                "Item schema v{} is newer than supported v{}",
                record.schema_version,
                CURRENT_RUNTIME_SCHEMA_VERSION
            );
        }
        Ok(record)
    }

    pub fn list_threads(&self) -> Result<Vec<ThreadRecord>> {
        let mut out = Vec::new();
        let threads_dir = checked_existing_runtime_store_dir(&self.threads_dir)?;
        for entry in fs::read_dir(&threads_dir)
            .with_context(|| format!("Failed to read {}", threads_dir.display()))?
        {
            let entry = entry?;
            let path = entry.path();
            if path.extension().is_none_or(|ext| ext != "json") {
                continue;

View on GitHub (pinned to 0c42157ee5)

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.

Defensive patterns

Strategy: validation

Validate before calling

// Rust: preflight the item file's schema version before load_item
let path = store.item_path(item_id)?;
if let Ok(raw) = std::fs::read_to_string(&path) {
    if let Ok(v) = serde_json::from_str::<serde_json::Value>(&raw) {
        if v.get("schema_version").and_then(|s| s.as_u64()).unwrap_or(0) > 2 {
            anyhow::bail!("item {item_id} uses a newer schema; upgrade Codewhale first");
        }
    }
}
let item = store.load_item(item_id)?;

Try / catch

// Rust: classify version-incompatibility errors for a targeted upgrade message
match store.load_item(item_id) {
    Ok(item) => Ok(item),
    Err(err) if err.to_string().contains("newer than supported") => {
        Err(anyhow::anyhow!("item store is from a newer Codewhale; upgrade: {err}"))
    }
    Err(err) => Err(err),
}

Prevention

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.

When it happens

Trigger: Calling RuntimeThreadStore::load_item(item_id) against a store written by a newer Codewhale build (schema_version > 2).

Common situations: Mixed-version installs sharing one data dir; rollback scenarios; opening archives produced by a newer release.

Related errors

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