BoundaryML/baml · critical · BamlSysError

Failed to load BAML library from

Error message

Failed to load BAML library from {path}: {source}

What it means

`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.

Solutions

1. Rebuild the native library for the current platform/architecture
2. Run `ldd` (Linux) / `otool -L` (macOS) on the file and install any missing dependent libraries
3. Re-download/rebuild the artifact if the file is corrupt or truncated

Example fix

// before
let lib = unsafe { Library::new("/usr/lib/libbaml_arm64.so")? }; // LoadFailed on x86_64
// after
let lib = unsafe { Library::new("/usr/lib/libbaml_x86_64.so")? };

fn is_loadable(path: &Path) -> bool {
    let meta = std::fs::metadata(path);
    #[cfg(target_os = "linux")]
    { meta.map(|m| m.is_file()).unwrap_or(false) && arch_matches(path) }
    #[cfg(not(target_os = "linux"))]
    { meta.map(|m| m.is_file()).unwrap_or(false) }
}

fn library_file_valid(path: &Path) -> bool { path.is_file() && std::fs::metadata(path).map(|m| m.len() > 0).unwrap_or(false) }

match load_baml_sys() {
    Err(BamlSysError::LoadFailed { path, source }) => {
        eprintln!("Cannot load {path}: {source}; check arch and dependent libs (ldd)");
    }
    Ok(sys) => { /* use sys */ }
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• BAML library not found. Searched paths
• {0}
• Engine not initialized. Call create_baml_runtime first.
• Expected Collector, got
• Expected string value for tag key

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

Appendix: source

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

//! Error types for baml-sys library loading.

use std::path::PathBuf;

/// Errors that can occur during library loading.
#[derive(Debug, thiserror::Error)]
#[allow(missing_docs)] // Error variants are self-documenting via #[error(...)]
pub enum BamlSysError {
    /// Library file not found at any search path.
    #[error("BAML library not found. Searched paths: {searched_paths:?}")]
    LibraryNotFound { searched_paths: Vec<PathBuf> },

    /// 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 },

View on GitHub (pinned to bd85ce9dee)