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

Upgrade to the Codewhale version that wrote the turn records.

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

Error message

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

What it means

load_turn applies the same forward-compatibility guard as threads to turn records: if a turn JSON's schema_version exceeds CURRENT_RUNTIME_SCHEMA_VERSION (2), loading stops with 'Turn schema vN is newer than supported v2'. Newer turns may have fields or semantics this build cannot honor, so refusing is safer than partial parsing.

Source

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

            .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,
                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,

View on GitHub (pinned to 0c42157ee5)

Solutions

Upgrade to the Codewhale version that wrote the turn records.
Use a fresh/empty data directory for the older version.
Inspect the turn file's schema_version to confirm the mismatch before migrating data.

Defensive patterns

Strategy: validation

Validate before calling

// Rust: check the turn file's schema_version before load_turn
let path = store.turn_path(turn_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!("turn {turn_id} uses a newer schema; upgrade Codewhale first");
        }
    }
}
let turn = store.load_turn(turn_id)?;

Try / catch

// Rust: catch and classify the version error distinctly from parse errors
match store.load_turn(turn_id) {
    Ok(turn) => Ok(turn),
    Err(err) if err.to_string().contains("newer than supported") => {
        Err(anyhow::anyhow!("turn store is from a newer Codewhale; upgrade: {err}"))
    }
    Err(err) => Err(err),
}

Prevention

Treat data dirs as forward-only: upgrade binaries before reading upgraded stores.
Verify schema_version when accepting turn files from other machines.
Log the store path and schema version at startup to detect mismatches early.

When it happens

Trigger: Calling RuntimeThreadStore::load_turn(turn_id) on a store whose turn JSON was written by a newer Codewhale; common when the same data dir is reused across versions.

Common situations: Downgrade after an upgrade; a teammate on a newer build shares their task data directory; restoring from a backup created by a newer release.

Related errors

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