{"record":{"id":"947c444ac3b40a73","repo":"zeroclaw-labs/zeroclaw","slug":"config-at-is-schema-version-from-newer-than","errorCode":null,"errorMessage":"config at {} is schema_version {from}, newer than this binary supports ({})","messagePattern":"config at (.+?) is schema_version (.+?), newer than this binary supports \\((.+?)\\)","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/zeroclaw-config/src/migration.rs","lineNumber":747,"sourceCode":"\npub fn ensure_disk_at_current_version(path: &Path) -> Result<()> {\n    let raw = match std::fs::read_to_string(path) {\n        Ok(s) => s,\n        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(()),\n        Err(e) => {\n            return Err(anyhow::Error::from(e)).with_context(|| {\n                format!(\"failed to read config at {}\", path.display().to_string())\n            });\n        }\n    };\n    let value: toml::Value =\n        toml::from_str(&raw).context(\"failed to parse config TOML for version check\")?;\n    let from = detect_version(&value)?;\n    if from == CURRENT_SCHEMA_VERSION {\n        return Ok(());\n    }\n    if from > CURRENT_SCHEMA_VERSION {\n        anyhow::bail!(\n            \"config at {} is schema_version {from}, newer than this binary supports ({})\",\n            path.display().to_string(),\n            CURRENT_SCHEMA_VERSION,\n        );\n    }\n    anyhow::bail!(\n        \"config at {} is schema_version {from}; run `zeroclaw config migrate` to update before modifying\",\n        path.display().to_string(),\n    );\n}\n\npub(crate) fn fold_string_into_array(\n    table: &mut toml::Table,\n    from_key: &str,\n    to_key: &str,\n) -> bool {\n    let value = match table.remove(from_key) {\n        Some(toml::Value::String(s)) if !s.is_empty() => s,","sourceCodeStart":729,"sourceCodeEnd":765,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-config/src/migration.rs#L729-L765","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: config.toml written by a newer binary, opened by an older one\nschema_version = 4\n\n// after: upgrade the binary instead of editing the file\n// $ zeroclaw --version  (must support schema_version 4)\n// or regenerate the config with the newer binary: $ zeroclaw config generate","handlingStrategy":"validation","validationCode":"fn disk_version(raw: &str) -> Option<u32> {\n    toml::from_str::<toml::Value>(raw)\n        .ok()?\n        .get(\"schema_version\")?\n        .as_integer()\n        .map(|v| v as u32)\n}\n\n// before calling any modifying config API\nif let Some(v) = disk_version(&std::fs::read_to_string(&path)?) {\n    if v > 3 {\n        // binary/config skew: upgrade the binary or regenerate the config; do not edit\n    }\n}","typeGuard":null,"tryCatchPattern":"match ensure_disk_at_current_version(&path) {\n    Err(e) if e.to_string().contains(\"newer than this binary supports\") => {\n        // version skew: upgrade the binary; editing the file will not help\n    }\n    other => other?,\n}","preventionTips":["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."],"tags":["config","migration","version-mismatch","downgrade"],"backgroundTag":"schema-version-newer-than-binary","analyzedSha":"88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc","analyzedAt":"2026-08-23T01:07:41.857Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}