Hmbown/CodeWhale · error

Thread schema v is newer than supported v

Error message

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

What it means

The runtime thread store reads each ThreadRecord from disk and checks its schema_version against MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION before use. A thread persisted by a newer Codewhale build carries a version this binary cannot interpret, so the record is rejected instead of being read incorrectly. This is forward-compatibility protection, not data corruption.

Solutions

1. Upgrade Codewhale back to the version (or newer) that wrote the thread.
2. Move the newer session directory aside or use a separate data dir for the old binary.
3. Check the record's schema_version in the store file to confirm the mismatch, and consult the changelog for the migration.
4. Do not hand-edit schema_version down; the layout may genuinely differ.

Example fix

// before: old binary reading newer store
$ codewhale-tui  # v1 with MAX v3, store at v4

// after: upgrade the binary so supported >= stored
$ cargo build --release -p codewhale-tui  # newer checkout, MAX v4

let v: serde_json::Value = serde_json::from_str(&std::fs::read_to_string(&thread_path)?)?;
let sv = v["schema_version"].as_u64().unwrap_or(0) as u32;
if sv > MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION {
    eprintln!("thread requires a newer build (schema v{sv})");
}

fn is_supported_schema(record: &ThreadRecord) -> bool {
    record.schema_version <= MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION
}

match store.load_thread(id) {
    Ok(t) => t,
    Err(e) if e.to_string().contains("newer than supported") => {
        eprintln!("upgrade codewhale to open this thread"); Default::default()
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Loading a thread from the runtime store after the store was written by a newer release whose RuntimeStoreRecordKind::Thread schema_version exceeds MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION of the running build.

Common situations: Downgrading Codewhale after a newer version migrated the store; sharing a session/data directory between two installs of different versions; resuming a session created by a dev/nightly build.

Related errors

• Codewhale stream-json schema did not match v0.9.1
• Item schema v is newer than supported v
• Turn schema v is newer than supported v
• Automation run schema v
• Automation schema v is newer than supported v

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/8d54ed0b421ed1b2. Report an issue: GitHub.

Appendix: source

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

        let path = self.thread_path(thread_id)?;
        let raw = read_store_file(&path).with_context(|| {
            RuntimeStoreRecordFailure::new(
                RuntimeStoreOperation::Read,
                RuntimeStoreRecordKind::Thread,
                thread_id,
                &path,
            )
        })?;
        let record: ThreadRecord = serde_json::from_str(&raw).with_context(|| {
            RuntimeStoreRecordFailure::new(
                RuntimeStoreOperation::Parse,
                RuntimeStoreRecordKind::Thread,
                thread_id,
                &path,
            )
        })?;
        if record.schema_version > MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION {
            bail!(
                "Thread schema v{} is newer than supported v{}",
                record.schema_version,
                MAX_SUPPORTED_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(|| {
            RuntimeStoreRecordFailure::new(
                RuntimeStoreOperation::Read,
                RuntimeStoreRecordKind::Turn,
                turn_id,
                &path,
            )
        })?;

View on GitHub (pinned to 73e0f67d83)