BoundaryML/baml · error · BamlSysError

Failed to determine cache directory

Error message

Failed to determine cache directory: {0}

What it means

baml-sys could not determine the local cache directory used to store the downloaded BAML native library. The library resolves a cache location (typically honoring HOME/XDG_CACHE_HOME-style environment) before checking for or downloading the shared library; when that resolution fails, it wraps the underlying cause string in this error. Without a cache directory it cannot persist or find the native artifact.

Solutions

1. Set the HOME environment variable to a writable directory (e.g. export HOME=/tmp or the user's home)
2. Set XDG_CACHE_HOME to an existing writable directory
3. Run the program as a normal user with a valid home directory
4. Pass an explicit cache path if the API exposes one

Example fix

// before (CI container)
// no HOME set -> CacheDir error
// after (Dockerfile)
ENV HOME=/root
RUN mkdir -p /root/.cache

if std::env::var_os("HOME").is_none() && std::env::var_os("XDG_CACHE_HOME").is_none() {
    eprintln!("HOME/XDG_CACHE_HOME not set; baml-sys cache dir lookup may fail");
    std::env::set_var("XDG_CACHE_HOME", "/tmp/baml-cache");
    std::fs::create_dir_all("/tmp/baml-cache").ok();
}

fn has_cache_dir_env() -> bool {
    std::env::var_os("XDG_CACHE_HOME").map(|p| !p.is_empty()).unwrap_or_else(|| {
        std::env::var_os("HOME").map(|h| !h.is_empty()).unwrap_or(false)
    })
}

match baml_sys::init() {
    Ok(_) => {},
    Err(BamlSysError::CacheDir(msg)) => {
        eprintln!("cache dir lookup failed: {msg}; set HOME or XDG_CACHE_HOME");
        std::process::exit(1);
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: Calling any baml-sys init/load API when the cache-directory lookup fails: HOME unset, XDG_CACHE_HOME pointing at an invalid path, or the platform-specific dir routine returning an error (e.g. dir::cache_dir() returning None).

Common situations: Running in containerized/CI environments with a stripped environment (no HOME), systemd services or cron jobs with minimal env, or running as a user with no writable home.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Checksum mismatch: expected
• Could not determine home directory
• Environment variable
• Failed to download library
• Failed to resolve expression

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

Appendix: source

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

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

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

View on GitHub (pinned to bd85ce9dee)