BoundaryML/baml · error · BamlSysError

Failed to download library

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.

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

• Checksum mismatch: expected
• {err}
• Failed to download asset
• Failed to download checksum file
• Could not bind playground port

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

Appendix: 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)