zeroclaw-labs/zeroclaw · error · anyhow::Error

config at {} is schema_version {from}, newer than this binar

Error message

config at {} is schema_version {from}, newer than this binary supports ({})

What it means

Thrown by ensure_disk_at_current_version when the config file's schema_version is greater than the CURRENT_SCHEMA_VERSION the binary was compiled with (V3 in this tree). ZeroClaw stamps a schema version into every config so an older binary refuses to operate on a format whose fields it cannot interpret. Hitting this means a newer ZeroClaw binary wrote the config and an older build is now trying to open it.

Source

Thrown at crates/zeroclaw-config/src/migration.rs:747

pub fn ensure_disk_at_current_version(path: &Path) -> Result<()> {
    let raw = match std::fs::read_to_string(path) {
        Ok(s) => s,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(()),
        Err(e) => {
            return Err(anyhow::Error::from(e)).with_context(|| {
                format!("failed to read config at {}", path.display().to_string())
            });
        }
    };
    let value: toml::Value =
        toml::from_str(&raw).context("failed to parse config TOML for version check")?;
    let from = detect_version(&value)?;
    if from == CURRENT_SCHEMA_VERSION {
        return Ok(());
    }
    if from > CURRENT_SCHEMA_VERSION {
        anyhow::bail!(
            "config at {} is schema_version {from}, newer than this binary supports ({})",
            path.display().to_string(),
            CURRENT_SCHEMA_VERSION,
        );
    }
    anyhow::bail!(
        "config at {} is schema_version {from}; run `zeroclaw config migrate` to update before modifying",
        path.display().to_string(),
    );
}

pub(crate) fn fold_string_into_array(
    table: &mut toml::Table,
    from_key: &str,
    to_key: &str,
) -> bool {
    let value = match table.remove(from_key) {
        Some(toml::Value::String(s)) if !s.is_empty() => s,

View on GitHub (pinned to 88bb9c8533)

Solutions

Upgrade the zeroclaw binary to a version whose CURRENT_SCHEMA_VERSION is >= the value in the config.
Open the config with the newer binary and regenerate or export a V3-compatible config, then use that with the older binary.
Restore a backup of the config from before the newer binary touched it.
Last resort only: manually lower schema_version in the TOML after verifying the file uses no fields introduced after V3.

Example fix

// before: config.toml written by a newer binary, opened by an older one
schema_version = 4

// after: upgrade the binary instead of editing the file
// $ zeroclaw --version  (must support schema_version 4)
// or regenerate the config with the newer binary: $ zeroclaw config generate

Defensive patterns

Strategy: validation

Validate before calling

fn disk_version(raw: &str) -> Option<u32> {
    toml::from_str::<toml::Value>(raw)
        .ok()?
        .get("schema_version")?
        .as_integer()
        .map(|v| v as u32)
}

// before calling any modifying config API
if let Some(v) = disk_version(&std::fs::read_to_string(&path)?) {
    if v > 3 {
        // binary/config skew: upgrade the binary or regenerate the config; do not edit
    }
}

Try / catch

match ensure_disk_at_current_version(&path) {
    Err(e) if e.to_string().contains("newer than this binary supports") => {
        // version skew: upgrade the binary; editing the file will not help
    }
    other => other?,
}

Prevention

Pin one zeroclaw version per machine and per config directory.
Back up the config before running a newer binary against it.
Check the binary's supported schema version before pointing an old build at a config written by a new one.
Avoid syncing a single config file across machines running different versions.

When it happens

Trigger: Any code path that calls ensure_disk_at_current_version(path) on a TOML file whose detected schema_version is 4+ while the running binary's CURRENT_SCHEMA_VERSION is 3. Typical: downgrade the zeroclaw binary (or switch between a dev build and a release) after a newer build already wrote the config.

Common situations: Downgrading zeroclaw after testing a newer release; two binary versions on PATH; a config directory synced between machines running different versions; reverting to an old release branch while keeping a config written by main.

Related errors

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/947c444ac3b40a73. Report an issue: GitHub.