{"record":{"id":"467459bdf16de6bd","repo":"BoundaryML/baml","slug":"failed-to-load-baml-library-from-path-source","errorCode":null,"errorMessage":"Failed to load BAML library from {path}: {source}","messagePattern":"Failed to load BAML library from (.+?): (.+?)","errorType":"exception","errorClass":"BamlSysError","httpStatus":null,"severity":"critical","filePath":"languages/rust/baml-sys/src/error.rs","lineNumber":14,"sourceCode":"//! Error types for baml-sys library loading.\n\nuse std::path::PathBuf;\n\n/// Errors that can occur during library loading.\n#[derive(Debug, thiserror::Error)]\n#[allow(missing_docs)] // Error variants are self-documenting via #[error(...)]\npub enum BamlSysError {\n    /// Library file not found at any search path.\n    #[error(\"BAML library not found. Searched paths: {searched_paths:?}\")]\n    LibraryNotFound { searched_paths: Vec<PathBuf> },\n\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","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/languages/rust/baml-sys/src/error.rs#L1-L32","documentation":"`BamlSysError::LoadFailed` from baml-sys: the library file was found at `path` but `libloading` failed to load it, with the underlying `libloading::Error` attached as source. Common causes are incompatible architecture, missing transitive dependencies, or corrupt/truncated library files.","triggerScenarios":"Loading the BAML dynamic library whose file exists but is not a valid loadable module for the current process (wrong arch, unresolved dependent shared libraries, wrong OS format).","commonSituations":"x86_64 binary loading an aarch64 library; library built against a different glibc/libc; missing CUDA or other transitive deps; macOS library on Linux; partially downloaded artifact.","solutions":["Rebuild the native library for the current platform/architecture","Run `ldd` (Linux) / `otool -L` (macOS) on the file and install any missing dependent libraries","Re-download/rebuild the artifact if the file is corrupt or truncated"],"exampleFix":"// before\nlet lib = unsafe { Library::new(\"/usr/lib/libbaml_arm64.so\")? }; // LoadFailed on x86_64\n// after\nlet lib = unsafe { Library::new(\"/usr/lib/libbaml_x86_64.so\")? };","handlingStrategy":"validation","validationCode":"fn is_loadable(path: &Path) -> bool {\n    let meta = std::fs::metadata(path);\n    #[cfg(target_os = \"linux\")]\n    { meta.map(|m| m.is_file()).unwrap_or(false) && arch_matches(path) }\n    #[cfg(not(target_os = \"linux\"))]\n    { meta.map(|m| m.is_file()).unwrap_or(false) }\n}","typeGuard":"fn library_file_valid(path: &Path) -> bool { path.is_file() && std::fs::metadata(path).map(|m| m.len() > 0).unwrap_or(false) }","tryCatchPattern":"match load_baml_sys() {\n    Err(BamlSysError::LoadFailed { path, source }) => {\n        eprintln!(\"Cannot load {path}: {source}; check arch and dependent libs (ldd)\");\n    }\n    Ok(sys) => { /* use sys */ }\n}","preventionTips":["Match library architecture to the host process","Run ldd/otool -L in CI to verify dependencies","Download artifacts with checksum verification to avoid corruption","Rebuild native libs when switching toolchains (glibc/musl)"],"tags":["rust","ffi","library-loading","dynamic-linking"],"backgroundTag":"module-init-failed","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"}