Hmbown/CodeWhale · error

Item schema v is newer than supported v

Error message

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

What it means

Same forward-compatibility guard as for threads, applied to a single ItemRecord fetched by id: if the stored item's schema_version exceeds the running binary's MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION, the item cannot be safely deserialized into known fields and the load fails. Only this item's lookup is refused; other items may still load.

Solutions

1. Upgrade the application to a build that supports the stored schema version.
2. Skip or archive the incompatible item; load the thread with a binary matching the writer version.
3. Use one data directory per app version to avoid mixed-version reads.
4. If the item is expendable, remove its store file so the thread can load.

Example fix

// before
let item = store.get_item(item_id)?; // fails on newer schema

// after: guard by checking version in the raw record first
let raw = read_store_file(&path)?;
let v: u32 = serde_json::from_slice::<serde_json::Value>(&raw)?["schema_version"]
    .take().as_u64().unwrap_or(0) as u32;
if v > MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION { skip_item(item_id); }

let raw = std::fs::read_to_string(&item_path)?;
let v: serde_json::Value = serde_json::from_str(&raw)?;
if v["schema_version"].as_u64().unwrap_or(0) as u32 > MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION {
    eprintln!("item written by a newer build; upgrade before reading");
}

fn item_supported(item: &ItemRecord) -> bool {
    item.schema_version <= MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION
}

match store.get_item(item_id) {
    Ok(i) => Some(i),
    Err(e) if e.to_string().contains("newer than supported") => { warn!("item skipped: newer schema"); None }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: Calling the store's get-item path (RuntimeStoreRecordKind::Item lookup by item_id) where the JSON on disk has schema_version > MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION.

Common situations: A newer app version wrote the item; downgrade or mixed-version installs sharing one data directory; opening a session exported from a newer release.

Related errors

• Codewhale stream-json schema did not match v0.9.1
• Thread 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/a89b03bb6729f73e. Report an issue: GitHub.

Appendix: source

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

        let path = self.item_path(item_id)?;
        let raw = read_store_file(&path).with_context(|| {
            RuntimeStoreRecordFailure::new(
                RuntimeStoreOperation::Read,
                RuntimeStoreRecordKind::Item,
                item_id,
                &path,
            )
        })?;
        let record: TurnItemRecord = serde_json::from_str(&raw).with_context(|| {
            RuntimeStoreRecordFailure::new(
                RuntimeStoreOperation::Parse,
                RuntimeStoreRecordKind::Item,
                item_id,
                &path,
            )
        })?;
        if record.schema_version > MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION {
            bail!(
                "Item schema v{} is newer than supported v{}",
                record.schema_version,
                MAX_SUPPORTED_RUNTIME_SCHEMA_VERSION
            );
        }
        if matches!(
            record.schema_version,
            IMAGE_RUNTIME_SCHEMA_VERSION | OUTPUT_LIMIT_RUNTIME_SCHEMA_VERSION
        ) && record.kind == TurnItemKind::UserMessage
        {
            record.user_content()?;
        }
        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)?;

View on GitHub (pinned to 73e0f67d83)