Hmbown/CodeWhale · error · anyhow::Error

continual harness state {} uses newer schema {}; this Codewh

Error message

continual harness state {} uses newer schema {}; this Codewhale supports schema {}

What it means

Thrown by load_state when the harness state file's schema_version is greater than SCHEMA_VERSION (1) supported by this binary. Version 0 is silently upgraded to 1, but a newer version means the file was written by a newer Codewhale and may contain fields this build cannot interpret safely, so loading fails closed.

Source

Thrown at crates/tui/src/continual_harness.rs:259

        Ok(raw) => raw,
        Err(error) if error.kind() == ErrorKind::NotFound => {
            return Ok(HarnessState {
                schema_version: SCHEMA_VERSION,
                entries: Vec::new(),
            });
        }
        Err(error) => {
            return Err(error)
                .with_context(|| format!("read continual harness state {}", path.display()));
        }
    };
    let mut state: HarnessState = serde_json::from_str(&raw)
        .with_context(|| format!("parse continual harness state {}", path.display()))?;
    if state.schema_version == 0 {
        state.schema_version = SCHEMA_VERSION;
    }
    if state.schema_version > SCHEMA_VERSION {
        bail!(
            "continual harness state {} uses newer schema {}; this Codewhale supports schema {}",
            path.display(),
            state.schema_version,
            SCHEMA_VERSION
        );
    }
    if state.entries.len() > MAX_ENTRIES {
        bail!(
            "continual harness state {} has {} entries; maximum is {MAX_ENTRIES}",
            path.display(),
            state.entries.len()
        );
    }
    Ok(state)
}

fn save_state(path: &Path, state: &HarnessState) -> Result<()> {
    let parent = path

View on GitHub (pinned to 0c42157ee5)

Solutions

Upgrade Codewhale to at least the version that wrote the state file
If the ledger is disposable, archive or delete the state file so it regenerates at the current schema
Do not hand-edit schema_version down unless you have verified the payload is compatible

Defensive patterns

Strategy: validation

Validate before calling

// Peek at the schema version before handing the workspace to this build:
let raw = std::fs::read_to_string(&state_path)?;
let version: u32 = serde_json::from_str::<serde_json::Value>(&raw)?
    .get("schema_version")
    .and_then(|v| v.as_u64()).unwrap_or(0) as u32;
if version > 1 {
    return Err(anyhow::anyhow!("state written by a newer Codewhale (schema {version}); upgrade this binary"));
}

Try / catch

match continual_harness::overview(&workspace) {
    Ok(overview) => { /* ... */ }
    Err(error) if error.to_string().contains("newer schema") => {
        // stop and tell the user to upgrade; do not rewrite the file
    }
    Err(error) => return Err(error),
}

Prevention

Keep one Codewhale version per workspace to avoid writing state a downgrade cannot read
Upgrade before downgrade-prone workflows (testing an old release) and archive the state file first
Never hand-edit schema_version to silence the error; the payload may not be compatible

When it happens

Trigger: Opening a workspace whose .codewhale harness state was written by a newer release, then running an older binary against it.

Common situations: Downgrading Codewhale; switching between stable and older builds on the same workspace; a teammate on a newer version committing workspace state.

Related errors

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