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

Upgrade Codewhale to at least the version that wrote the store, then retry.

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

Error message

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

What it means

load_thread reads a thread JSON file and compares its schema_version against CURRENT_RUNTIME_SCHEMA_VERSION (currently 2). A record written by a newer Codewhale whose schema major is higher cannot be interpreted correctly, so loading is refused rather than mis-parsed. This is forward-incompatibility detection for the on-disk thread store.

Source

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

        remove_file_if_exists(&self.turn_path(turn_id)?)
    }

    fn remove_thread(&self, thread_id: &str) -> Result<()> {
        remove_file_if_exists(&self.thread_path(thread_id)?)
    }

    fn remove_item(&self, item_id: &str) -> Result<()> {
        remove_file_if_exists(&self.item_path(item_id)?)
    }

    pub fn load_thread(&self, thread_id: &str) -> Result<ThreadRecord> {
        let path = self.thread_path(thread_id)?;
        let raw = read_store_file(&path)
            .with_context(|| format!("Failed to read thread {}", path.display()))?;
        let record: ThreadRecord = serde_json::from_str(&raw)
            .with_context(|| format!("Failed to parse thread {}", path.display()))?;
        if record.schema_version > CURRENT_RUNTIME_SCHEMA_VERSION {
            bail!(
                "Thread schema v{} is newer than supported v{}",
                record.schema_version,
                CURRENT_RUNTIME_SCHEMA_VERSION
            );
        }
        Ok(record)
    }

    pub fn load_turn(&self, turn_id: &str) -> Result<TurnRecord> {
        let path = self.turn_path(turn_id)?;
        let raw = read_store_file(&path)
            .with_context(|| format!("Failed to read turn {}", path.display()))?;
        let record: TurnRecord = serde_json::from_str(&raw)
            .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,

View on GitHub (pinned to 0c42157ee5)

Solutions

Upgrade Codewhale to at least the version that wrote the store, then retry.
Point the runtime at a fresh data directory if you intentionally need the older version and do not need old threads.
Check the schema_version field in the thread JSON to confirm which version wrote it before choosing rollback vs upgrade.

Example fix

# before
# data dir last written by codewhale 3.x, running 2.x
codewhale threads show <id>   # bails: Thread schema v3 is newer than supported v2

# after
# upgrade to the version that wrote the store
codewhale upgrade && codewhale threads show <id>

Defensive patterns

Strategy: validation

Validate before calling

// Rust: probe a record's schema version before handing it to the store
fn schema_version_of(path: &std::path::Path) -> Option<u32> {
    let raw = std::fs::read_to_string(path).ok()?;
    serde_json::from_str::<serde_json::Value>(&raw).ok()?
        .get("schema_version")?
        .as_u64()
        .map(|v| v as u32)
}

if let Some(v) = schema_version_of(&thread_path) {
    anyhow::ensure!(v <= 2, "thread {thread_id} needs schema v{v}; upgrade Codewhale");
}
let record = store.load_thread(thread_id)?;

Try / catch

// Rust: distinguish version rejection from IO/parse errors and surface an upgrade hint
match store.load_thread(thread_id) {
    Ok(record) => Ok(record),
    Err(err) if err.to_string().contains("newer than supported") => {
        Err(anyhow::anyhow!("store written by a newer Codewhale; upgrade before reading: {err}"))
    }
    Err(err) => Err(err),
}

Prevention

Never reopen a data directory with an older binary after an upgrade.
Check schema_version in exported/shared JSON before importing it.
Pin each Codewhale version to its own data dir, or migrate forward only.

When it happens

Trigger: Calling RuntimeThreadStore::load_thread(thread_id) where the stored thread JSON has schema_version > 2; typically after downgrading Codewhale or pointing the data dir at a store written by a newer build.

Common situations: Rolling back to an older release while keeping the same task-data directory; sharing a data dir between two installed versions; opening a backup made by a newer version.

Related errors

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