BoundaryML/baml · error · BamlSysError

IO error: {0}

Error message

IO error: {0}

What it means

A generic std::io::Error occurred during baml-sys library-loading operations and was converted into this variant via #[from]. Typical sources include failing to create the cache directory, failing to read/write the downloaded library file, or filesystem permission problems. The wrapped message describes the underlying OS error.

Source

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

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

/// Result type for baml-sys operations.
pub type Result<T> = std::result::Result<T, BamlSysError>;

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Check and fix permissions on the cache directory (or point it somewhere writable)
2. Free disk space if the filesystem is full
3. Check dmesg/audit logs for filesystem errors or EDR interference
4. Run with strace or enable logging to see which file operation fails
5. Ensure the cache parent directory exists and is writable by the running user

Example fix

// before
# running as nobody with read-only /home
// after
export XDG_CACHE_HOME=/tmp/baml-cache
mkdir -p /tmp/baml-cache

let cache = std::env::var_os("XDG_CACHE_HOME")
    .or_else(|| std::env::var_os("HOME").map(|h| h.join(".cache").into()))
    .expect("no cache location");
let md = std::fs::metadata(&cache)?;
assert!(!md.permissions().readonly(), "cache dir is read-only");

fn cache_writable() -> bool {
    std::env::var_os("HOME")
        .or_else(|| std::env::var_os("XDG_CACHE_HOME"))
        .and_then(|p| std::fs::create_dir_all(&p).ok().map(|_| true))
        .unwrap_or(false)
}

match baml_sys::init() {
    Err(BamlSysError::Io(e)) if e.kind() == std::io::ErrorKind::PermissionDenied => {
        eprintln!("cache path not writable: {e}; set XDG_CACHE_HOME");
    }
    Err(BamlSysError::Io(e)) if e.kind() == std::io::ErrorKind::StorageFull => {
        eprintln!("disk full: {e}");
    }
    other => other.map(|_| ())?,
}

When it happens

Trigger: Cache directory cannot be created (permissions, read-only filesystem, disk full), the downloaded library file cannot be written or read back, or file metadata/hashing reads fail with an OS error.

Common situations: Read-only container filesystems, running as a user without write access to the cache path, disk-quota exhaustion, or antivirus/EDR locking the downloaded .so/.dll/.dylib file.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• no filesystem is attached to this server ({})
• disk error: {0}
• profiling store contains a symlink
• profiling store contains an unsupported file type
• failed to install {} into {}

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