Hmbown/CodeWhale · error

Runtime turn operation binding schema v

Error message

Runtime turn operation binding schema v{} is newer than supported v{}

What it means

RuntimeTurnOperationBinding::validate compares the binding record's schema_version to TURN_OPERATION_BINDING_SCHEMA_VERSION (currently 1). A binding stamped by a newer binary is refused, along with further checks on thread id and other fields. This keeps claim/lock metadata interpretable by the running process.

Solutions

1. Upgrade to the newer build that wrote the binding.
2. Delete the stale binding file once no process owns the turn operation, then retry the claim.
3. Use one runtime store directory per app version.
4. Check schema_version in the binding JSON; a value of 1 or less with this error indicates a different problem (corrupt file) to investigate separately.

Example fix

// before: stale binding blocks startup
$ rm ~/.local/share/codewhale/runtime/turn-bindings/<op-id>.json

// after (programmatic)
match binding {
    Ok(b) => use_binding(b),
    Err(e) if e.to_string().contains("newer than supported") => {
        remove_stale_binding(&path)?; // only if no live owner
        retry_claim(key)?;
    }
    Err(e) => return Err(e),
}

let v: serde_json::Value = serde_json::from_str(&std::fs::read_to_string(&binding_path)?)?;
if v["schema_version"].as_u64().unwrap_or(1) > TURN_OPERATION_BINDING_SCHEMA_VERSION as u64 {
    eprintln!("binding written by newer build; remove only if no live owner");
}

fn binding_supported(b: &RuntimeTurnOperationBinding) -> bool {
    b.schema_version <= TURN_OPERATION_BINDING_SCHEMA_VERSION
}

match binding.validate() {
    Ok(()) => proceed(binding),
    Err(e) if e.to_string().contains("newer than supported") => {
        if !owner_alive(&binding) { remove(&path)?; retry_claim(key)?; }
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Validating a persisted turn-operation binding (claim/lock file) whose schema_version is greater than TURN_OPERATION_BINDING_SCHEMA_VERSION — i.e., the file was written by a newer release that bumped the binding schema.

Common situations: Downgrading Codewhale while leftover binding files from a newer version remain in the store; two versions of the app sharing one runtime directory; a crash left a binding that the old binary cannot validate.

Related errors

• Automation run schema v
• Automation schema v is newer than supported v
• Checkpoint schema v is newer than supported v
• Codewhale stream-json contained an unknown event type
• Codewhale stream-json schema did not match v0.9.1

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

Appendix: source

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

        .map(parse_runtime_reasoning_effort)
        .transpose()
        .map(|effort| effort.map(|effort| effort.as_setting().to_string()))
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
struct RuntimeTurnOperationBinding {
    schema_version: u32,
    thread_id: String,
    turn_id: String,
    operation_key_fingerprint: String,
    request_fingerprint: String,
    created_at: DateTime<Utc>,
}

impl RuntimeTurnOperationBinding {
    fn validate(&self) -> Result<()> {
        if self.schema_version > TURN_OPERATION_BINDING_SCHEMA_VERSION {
            bail!(
                "Runtime turn operation binding schema v{} is newer than supported v{}",
                self.schema_version,
                TURN_OPERATION_BINDING_SCHEMA_VERSION
            );
        }
        validated_record_id(&self.thread_id, "operation thread id")?;
        validated_record_id(&self.turn_id, "operation turn id")?;
        validate_sha256_fingerprint(&self.operation_key_fingerprint, "operation key fingerprint")?;
        validate_sha256_fingerprint(&self.request_fingerprint, "operation request fingerprint")?;
        Ok(())
    }
}

#[derive(Debug, Clone)]
struct PreparedRuntimeTurnOperation {
    binding: RuntimeTurnOperationBinding,
    requested_turn_id: Option<String>,
}

View on GitHub (pinned to 73e0f67d83)