{"record":{"id":"fca49783d1ea0885","repo":"BoundaryML/baml","slug":"version-mismatch-rust-package-expects-expected-but-library","errorCode":null,"errorMessage":"Version mismatch: Rust package expects {expected}, but library reports {actual}","messagePattern":"Version mismatch: Rust package expects (.+?), but library reports (.+?)","errorType":"exception","errorClass":"BamlSysError","httpStatus":null,"severity":"critical","filePath":"languages/rust/baml-sys/src/error.rs","lineNumber":30,"sourceCode":"\n    /// Failed to load the dynamic library.\n    #[error(\"Failed to load BAML library from {path}: {source}\")]\n    LoadFailed {\n        path: PathBuf,\n        #[source]\n        source: libloading::Error,\n    },\n\n    /// Symbol not found in loaded library.\n    #[error(\"Symbol '{symbol}' not found in BAML library: {source}\")]\n    SymbolNotFound {\n        symbol: &'static str,\n        #[source]\n        source: libloading::Error,\n    },\n\n    /// Version mismatch between Rust package and loaded library.\n    #[error(\"Version mismatch: Rust package expects {expected}, but library reports {actual}\")]\n    VersionMismatch { expected: String, actual: String },\n\n    /// Platform not supported.\n    #[error(\"Platform not supported: {os}/{arch}\")]\n    UnsupportedPlatform {\n        os: &'static str,\n        arch: &'static str,\n    },\n\n    /// Failed to determine cache directory.\n    #[error(\"Failed to determine cache directory: {0}\")]\n    CacheDir(String),\n\n    /// Download failed.\n    #[error(\"Failed to download library: {0}\")]\n    DownloadFailed(String),\n\n    /// Checksum mismatch after download.","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/languages/rust/baml-sys/src/error.rs#L12-L48","documentation":"`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.","triggerScenarios":"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.","commonSituations":"`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.","solutions":["Upgrade or reinstall the native BAML library to the version matching the Rust package","Pin/align both the Rust package and native library to the same release","Clear stale cached library artifacts and rebuild from the matching source"],"exampleFix":"// before\n# lib reports 0.8.0, Rust crate expects 0.9.0\n// after\n$ baml-cli install --version 0.9.0  # or rebuild native lib from the matching tag","handlingStrategy":"validation","validationCode":"let reported = get_library_version(lib_path)?;\nlet expected = baml_sys::EXPECTED_VERSION;\nif reported != expected { eprintln!(\"reinstall native lib: expected {expected}, got {reported}\"); }","typeGuard":"fn version_matches(actual: &str, expected: &str) -> bool { actual == expected }","tryCatchPattern":"match load_baml_sys() {\n    Err(BamlSysError::VersionMismatch { expected, actual }) => {\n        eprintln!(\"Reinstall native library: Rust expects {expected}, library is {actual}\");\n    }\n    Ok(sys) => { /* use sys */ }\n}","preventionTips":["Install the native library from the same release as the Rust crate","Never mix versions across upgrades; upgrade both sides atomically","Pin artifact versions in lockfiles/install scripts","Clear cached native libs before rebuilding"],"tags":["rust","ffi","version-mismatch","abi"],"backgroundTag":"version-mismatch","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}