BoundaryML/baml · error · FetchError

manifest schema {got} not supported (max {max}); run `baml s

Error message

manifest schema {got} not supported (max {max}); run `baml self-update`

What it means

FetchError::ManifestSchemaTooNew is thrown by baml_release when a downloaded release manifest declares a schema version greater than the maximum this installed binary supports. This is a forward-compatibility guard: a newer release format cannot be safely parsed by an older CLI. The error explicitly instructs the user to run `baml self-update` to obtain a binary that understands the new schema.

Source

Thrown at baml_language/crates/baml_release/src/lib.rs:87

        match self {
            Product::Toolchain => "baml-language",
            Product::Wrapper => "baml-wrapper",
        }
    }
}

#[derive(Debug, thiserror::Error)]
pub enum FetchError {
    #[error("network error fetching {url}: {source}")]
    Network { url: String, source: reqwest::Error },
    #[error("HTTP {status} fetching {url}")]
    HttpStatus {
        url: String,
        status: reqwest::StatusCode,
    },
    #[error("manifest 404 for version {version} (not released yet?)")]
    ManifestNotFound { version: String },
    #[error("manifest schema {got} not supported (max {max}); run `baml self-update`")]
    ManifestSchemaTooNew { got: u32, max: u32 },
    #[error("target {target} not built for version {version}")]
    TargetNotInManifest { target: String, version: String },
    #[error("sha256 mismatch for {url}: expected {expected}, got {got}")]
    ChecksumMismatch {
        url: String,
        expected: String,
        got: String,
    },
    #[error("archive missing expected binary {name}")]
    BinaryNotInArchive { name: String },
    #[error("archive contains unsafe path {path}")]
    UnsafeArchivePath { path: String },
    #[error("disk error: {0}")]
    Io(#[from] std::io::Error),
    #[error("zip archive error: {0}")]
    Zip(#[from] zip::result::ZipError),
}

View on GitHub (pinned to bd85ce9dee)

Solutions

Run `baml self-update` (or reinstall the CLI) to get a binary supporting the new schema
Update the BAML CLI via your package manager (npm/pip/brew) if self-update is unavailable
If you must stay pinned, fetch a manifest URL frozen to your supported schema version (if offered)
Report/inspect: if the schema bump is accidental, check for a recent BAML release announcement

Example fix

# before (old CLI, new schema)
$ baml install 0.204.0
manifest schema 2 not supported (max 1); run `baml self-update`
# after
$ baml self-update
$ baml install 0.204.0

Defensive patterns

Strategy: try-catch

Validate before calling

// peek schema before full processing
let schema: u32 = peek_manifest_schema(&manifest);
if schema > MAX_SUPPORTED_SCHEMA {
    eprintln!("manifest schema {schema} too new; update the CLI first");
}

Type guard

fn is_schema_too_new(e: &FetchError) -> bool {
    matches!(e, FetchError::ManifestSchemaTooNew { .. })
}

Try / catch

match fetch_manifest(url) {
    Err(FetchError::ManifestSchemaTooNew { got, max }) => {
        eprintln!("manifest schema {got} > supported {max}; run `baml self-update`");
        std::process::exit(1);
    }
    other => other,
}

Prevention

Keep the BAML CLI reasonably up to date
Pin to schema-frozen manifest URLs in CI if available
Subscribe to BAML release notes for schema bumps
In air-gapped environments, mirror manifests at a pinned schema version

When it happens

Trigger: Fetching a release manifest (typically during self-update or tool installation) whose 'schema' field exceeds the max supported by the current code's schema parser.

Common situations: The BAML project bumped the manifest schema and you are running an old CLI against the always-current manifest URL; stale binaries in CI; frozen/air-gapped installs pointing at a live manifest.

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 BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/95776975095046f5. Report an issue: GitHub.