BoundaryML/baml · critical · BamlSysError

Version mismatch: Rust package expects

Error message

Version mismatch: Rust package expects {expected}, but library reports {actual}

What it means

`BamlSysError::VersionMismatch` from baml-sys: the Rust package's expected ABI/version string differs from the version the loaded native library reports. Loading incompatible versions would cause undefined behavior, so the loader refuses to proceed.

Solutions

1. Upgrade or reinstall the native BAML library to the version matching the Rust package
2. Pin/align both the Rust package and native library to the same release
3. Clear stale cached library artifacts and rebuild from the matching source

Example fix

// before
# lib reports 0.8.0, Rust crate expects 0.9.0
// after
$ baml-cli install --version 0.9.0  # or rebuild native lib from the matching tag

let reported = get_library_version(lib_path)?;
let expected = baml_sys::EXPECTED_VERSION;
if reported != expected { eprintln!("reinstall native lib: expected {expected}, got {reported}"); }

fn version_matches(actual: &str, expected: &str) -> bool { actual == expected }

match load_baml_sys() {
    Err(BamlSysError::VersionMismatch { expected, actual }) => {
        eprintln!("Reinstall native library: Rust expects {expected}, library is {actual}");
    }
    Ok(sys) => { /* use sys */ }
}

When it happens

Trigger: Loading a native BAML library whose reported version string differs from the constant baked into the Rust baml-sys package — typically after upgrading one side without the other.

Common situations: `cargo update` bumped the Rust package but an old cached native lib is still installed; native lib rebuilt from main while Rust package pins an older ABI; mixed installs across machines.

Related errors

• Symbol ' ' not found in BAML library
• {0}
• BAML library not found. Searched paths
• Engine not initialized. Call create_baml_runtime first.
• error decoding value:

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/fca49783d1ea0885. Report an issue: GitHub.

Appendix: source

Thrown at languages/rust/baml-sys/src/error.rs:30

    /// Failed to load the dynamic library.
    #[error("Failed to load BAML library from {path}: {source}")]
    LoadFailed {
        path: PathBuf,
        #[source]
        source: libloading::Error,
    },

    /// Symbol not found in loaded library.
    #[error("Symbol '{symbol}' not found in BAML library: {source}")]
    SymbolNotFound {
        symbol: &'static str,
        #[source]
        source: libloading::Error,
    },

    /// Version mismatch between Rust package and loaded library.
    #[error("Version mismatch: Rust package expects {expected}, but library reports {actual}")]
    VersionMismatch { expected: String, actual: String },

    /// Platform not supported.
    #[error("Platform not supported: {os}/{arch}")]
    UnsupportedPlatform {
        os: &'static str,
        arch: &'static str,
    },

    /// Failed to determine cache directory.
    #[error("Failed to determine cache directory: {0}")]
    CacheDir(String),

    /// Download failed.
    #[error("Failed to download library: {0}")]
    DownloadFailed(String),

    /// Checksum mismatch after download.

View on GitHub (pinned to bd85ce9dee)