bundle at has schema_version ; this build understands

Error message

bundle at {source} has schema_version {}; this build understands {BUNDLE_SCHEMA_VERSION}

What it means

The bundle's `schema_version` field is a version this build does not understand (`BUNDLE_SCHEMA_VERSION`). The CLI refuses any bundle whose schema version is not exactly the one it supports, because field semantics may change across versions. Raised by `validate_bundle` immediately after the kind check during bundle parsing/import.

Solutions

Upgrade the codewhale CLI to a build whose BUNDLE_SCHEMA_VERSION matches the bundle, then re-run the import.
Re-export the bundle with the current CLI version so schema_version matches.
If you must use an older bundle, migrate its contents manually to the current schema (bump schema_version and adjust changed fields).

Example fix

// before (bundle.json)
{ "kind": "...", "schema_version": 3, ... }
// after (schema this build understands)
{ "kind": "...", "schema_version": 2, ... }  // or upgrade the CLI instead

Defensive patterns

Strategy: validation

Validate before calling

let v: serde_json::Value = serde_json::from_str(&text)?;
match v.get("schema_version").and_then(|s| s.as_u64()) {
    Some(n) if n == SUPPORTED_SCHEMA_VERSION => Ok(()),
    other => Err(format!("bundle schema_version {other:?} unsupported; this build understands {SUPPORTED_SCHEMA_VERSION}")),
}

Type guard

fn has_supported_schema(v: &serde_json::Value, supported: u64) -> bool {
    v.get("schema_version").and_then(|s| s.as_u64()) == Some(supported)
}

Prevention

Pin team members to compatible CLI versions when sharing bundles.
Re-export bundles after every CLI upgrade.
Check schema_version in the bundle header before distributing it.

When it happens

Trigger: Importing a bundle exported by a newer codewhale release (higher schema_version) or an older one (lower schema_version) into this build.

Common situations: Upgrading the CLI and then importing bundles generated by the previous release; sharing bundles between machines with different codewhale versions; a stale bundle checked into a repo before a schema bump.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at crates/cli/src/config_bundles.rs:237

    let mut path = Vec::new();
    NoDuplicates { path: &mut path }
        .deserialize(&mut deserializer)
        .map_err(|error| anyhow::anyhow!("{error}"))?;
    deserializer
        .end()
        .map_err(|error| anyhow::anyhow!("{error}"))?;
    Ok(())
}

fn validate_bundle(bundle: &PortableBundle, source: &str) -> Result<()> {
    if bundle.kind != BUNDLE_KIND {
        bail!(
            "bundle at {source} has kind {:?}; expected {BUNDLE_KIND:?}",
            bundle.kind
        );
    }
    if bundle.schema_version != BUNDLE_SCHEMA_VERSION {
        bail!(
            "bundle at {source} has schema_version {}; this build understands {BUNDLE_SCHEMA_VERSION}",
            bundle.schema_version
        );
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// Secret rejection
// ---------------------------------------------------------------------------

/// One rejected entry: the dotted key path and the reason. Values are never
/// included — the reason and path are all a reviewer needs.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RejectedEntry {
    pub key: String,
    pub reason: String,
}

View on GitHub (pinned to 73e0f67d83)