BoundaryML/baml · error · BamlSysError

Failed to download library: {0}

Error message

Failed to download library: {0}

What it means

The BAML native shared library was not present in the cache, so baml-sys attempted to download it and the HTTP download failed. The wrapped string carries the underlying cause (network error, bad URL, non-success status, or failure to write the file). The library cannot load the native component until the download succeeds.

Source

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

    },

    /// 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.
    #[error("Checksum mismatch: expected {expected}, got {actual}")]
    ChecksumMismatch { expected: String, actual: String },

    /// IO error.
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    /// Library already initialized with different path.
    #[error("Library already initialized from {existing_path}, cannot change to {requested_path}")]
    AlreadyInitialized {
        existing_path: PathBuf,
        requested_path: PathBuf,
    },
}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Check network connectivity to the download host from the failing machine
2. Configure proxy environment variables (HTTPS_PROXY) if behind a corporate proxy
3. Retry after a transient network failure (the download will restart)
4. Pre-seed the cache directory with the library artifact so no download is needed
5. Verify the BAML version you requested actually has a published artifact

Example fix

// before
curl https://download-host/...  # fails behind proxy
// after
export HTTPS_PROXY=http://proxy.corp:8080

let url = download_url();
let reachable = std::net::TcpStream::connect((host_of(&url), 443)).is_ok();
if !reachable {
    eprintln!("download host unreachable; check network/proxy before init");
}

fn is_transient_network_err(msg: &str) -> bool {
    msg.contains("timed out") || msg.contains("connection") || msg.contains("resolve")
}

match baml_sys::init() {
    Err(BamlSysError::DownloadFailed(msg)) if is_transient_network_err(&msg) => {
        // exponential backoff retry, then fail
    }
    Err(BamlSysError::DownloadFailed(msg)) => {
        eprintln!("download failed permanently: {msg}; pre-seed cache");
    }
    other => other.map(|_| ())?,
}

When it happens

Trigger: First-time load/init with a cold cache when the network is down, the download URL is unreachable or returns non-200, a proxy blocks the request, or the response body cannot be written to disk.

Common situations: Air-gapped or firewalled CI runners, corporate proxies requiring auth, DNS failures, transient network flaps during first install, or a version whose artifact was removed from the server.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• {err}
• Failed to download asset: {e}
• Failed to download checksum file: {e}
• Checksum mismatch: expected {expected}, got {actual}
• Could not find an available port in range {}..{}

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