{"record":{"id":"26cfeb907fadd6dd","repo":"BoundaryML/baml","slug":"failed-to-determine-cache-directory-0","errorCode":null,"errorMessage":"Failed to determine cache directory: {0}","messagePattern":"Failed to determine cache directory: (.+?)","errorType":"exception","errorClass":"BamlSysError","httpStatus":null,"severity":"error","filePath":"languages/rust/baml-sys/src/error.rs","lineNumber":41,"sourceCode":"    SymbolNotFound {\n        symbol: &'static str,\n        #[source]\n        source: libloading::Error,\n    },\n\n    /// Version mismatch between Rust package and loaded library.\n    #[error(\"Version mismatch: Rust package expects {expected}, but library reports {actual}\")]\n    VersionMismatch { expected: String, actual: String },\n\n    /// Platform not supported.\n    #[error(\"Platform not supported: {os}/{arch}\")]\n    UnsupportedPlatform {\n        os: &'static str,\n        arch: &'static str,\n    },\n\n    /// Failed to determine cache directory.\n    #[error(\"Failed to determine cache directory: {0}\")]\n    CacheDir(String),\n\n    /// Download failed.\n    #[error(\"Failed to download library: {0}\")]\n    DownloadFailed(String),\n\n    /// Checksum mismatch after download.\n    #[error(\"Checksum mismatch: expected {expected}, got {actual}\")]\n    ChecksumMismatch { expected: String, actual: String },\n\n    /// IO error.\n    #[error(\"IO error: {0}\")]\n    Io(#[from] std::io::Error),\n\n    /// Library already initialized with different path.\n    #[error(\"Library already initialized from {existing_path}, cannot change to {requested_path}\")]\n    AlreadyInitialized {\n        existing_path: PathBuf,","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/languages/rust/baml-sys/src/error.rs#L23-L59","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Set the HOME environment variable to a writable directory (e.g. export HOME=/tmp or the user's home)","Set XDG_CACHE_HOME to an existing writable directory","Run the program as a normal user with a valid home directory","Pass an explicit cache path if the API exposes one"],"exampleFix":"// before (CI container)\n// no HOME set -> CacheDir error\n// after (Dockerfile)\nENV HOME=/root\nRUN mkdir -p /root/.cache","handlingStrategy":"validation","validationCode":"if std::env::var_os(\"HOME\").is_none() && std::env::var_os(\"XDG_CACHE_HOME\").is_none() {\n    eprintln!(\"HOME/XDG_CACHE_HOME not set; baml-sys cache dir lookup may fail\");\n    std::env::set_var(\"XDG_CACHE_HOME\", \"/tmp/baml-cache\");\n    std::fs::create_dir_all(\"/tmp/baml-cache\").ok();\n}","typeGuard":"fn has_cache_dir_env() -> bool {\n    std::env::var_os(\"XDG_CACHE_HOME\").map(|p| !p.is_empty()).unwrap_or_else(|| {\n        std::env::var_os(\"HOME\").map(|h| !h.is_empty()).unwrap_or(false)\n    })\n}","tryCatchPattern":"match baml_sys::init() {\n    Ok(_) => {},\n    Err(BamlSysError::CacheDir(msg)) => {\n        eprintln!(\"cache dir lookup failed: {msg}; set HOME or XDG_CACHE_HOME\");\n        std::process::exit(1);\n    }\n    Err(e) => return Err(e.into()),\n}","preventionTips":["Always set HOME in container/CI images","Point XDG_CACHE_HOME at a writable volume in sandboxed environments","Smoke-test library loading in the same environment config used in production","Run services as a user with a valid home directory"],"tags":["rust","cache-directory","environment","native-library"],"backgroundTag":"missing-env-var","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}