{"record":{"id":"b30867d39eca55e4","repo":"rust-lang/cargo","slug":"could-not-find-cargo-home-dir","errorCode":null,"errorMessage":"could not find cargo home dir","messagePattern":"could not find cargo home dir","errorType":"exception","errorClass":"io::Error","httpStatus":null,"severity":"error","filePath":"crates/home/src/env.rs","lineNumber":79,"sourceCode":"/// Variant of `cargo_home_with_cwd` where the environment source is\n/// parameterized.\n///\n/// This is specifically to support in-process testing scenarios\n/// as environment variables and user home metadata are normally process global\n/// state. See the `OsEnv` trait.\npub fn cargo_home_with_cwd_env(env: &dyn Env, cwd: &Path) -> io::Result<PathBuf> {\n    match env.var_os(\"CARGO_HOME\").filter(|h| !h.is_empty()) {\n        Some(home) => {\n            let home = PathBuf::from(home);\n            if home.is_absolute() {\n                Ok(home)\n            } else {\n                Ok(cwd.join(&home))\n            }\n        }\n        _ => home_dir_with_env(env)\n            .map(|p| p.join(\".cargo\"))\n            .ok_or_else(|| io::Error::new(io::ErrorKind::Other, \"could not find cargo home dir\")),\n    }\n}\n\n/// Variant of `cargo_home_with_cwd` where the environment source is\n/// parameterized.\n///\n/// This is specifically to support in-process testing scenarios\n/// as environment variables and user home metadata are normally process global\n/// state. See the `OsEnv` trait.\npub fn rustup_home_with_env(env: &dyn Env) -> io::Result<PathBuf> {\n    let cwd = env.current_dir()?;\n    rustup_home_with_cwd_env(env, &cwd)\n}\n\n/// Variant of `cargo_home_with_cwd` where the environment source is\n/// parameterized.\n///\n/// This is specifically to support in-process testing scenarios","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/rust-lang/cargo/blob/eb98b54bc9f3c74519f43d066cb3fd02ebc88df0/crates/home/src/env.rs#L61-L97","documentation":"`cargo_home_with_cwd_env` resolves the Cargo home directory. If `CARGO_HOME` is set and non-empty it is used (joined to cwd if relative); otherwise it falls back to `home_dir_with_env(env)` appended with `.cargo`. If the home directory cannot be determined (the OS/env provides no home), the function returns an `io::Error` (kind `Other`, message `\"could not find cargo home dir\"`). Cargo cannot locate its registry/cache/store without this.","triggerScenarios":"Running Cargo (or a library resolving cargo home) in an environment where `CARGO_HOME` is unset/empty AND the home directory cannot be derived from env vars (`HOME` on Unix, `USERPROFILE`/tokens on Windows) via `home_dir_with_env`. Returns `Err`.","commonSituations":"Minimal containers/sandboxes without `HOME` set, systemd services or cron jobs with a cleared environment, running as a user with no home directory entry, or test harnesses that scrub environment variables.","solutions":["Set `CARGO_HOME` explicitly to an absolute, writable directory (e.g. `export CARGO_HOME=/path/to/.cargo`).","Ensure `HOME` (Unix) or `USERPROFILE` (Windows) is set to a valid, accessible home directory.","For service/cron contexts, define `CARGO_HOME` (and `HOME`) in the unit/environment file."],"exampleFix":"# before (env scrubbed, no HOME/CARGO_HOME)\ncargo build  # -> could not find cargo home dir\n\n# after\nexport CARGO_HOME=/var/lib/ci/.cargo\nexport HOME=/var/lib/ci\ncargo build","handlingStrategy":"fallback","validationCode":"use std::path::PathBuf;\nfn resolve_cargo_home() -> Result<PathBuf, String> {\n    if let Ok(h) = std::env::var(\"CARGO_HOME\") { if !h.is_empty() { return Ok(PathBuf::from(h)); } }\n    if let Ok(h) = std::env::var(\"HOME\") { if !h.is_empty() { return Ok(PathBuf::from(h).join(\".cargo\")); } }\n    Err(\"set CARGO_HOME or HOME\".into())\n}\n// ensure this returns Ok before invoking Cargo-dependent code","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set CARGO_HOME explicitly in CI, services, and containers.","Do not scrub HOME from the environment when Cargo must run.","Document the required environment variables in deployment runbooks."],"tags":["environment","cargo-home","home-dir","config","cargo"],"backgroundTag":null,"analyzedSha":"eb98b54bc9f3c74519f43d066cb3fd02ebc88df0","analyzedAt":"2026-08-11T17:42:36.556Z","contentChangedAt":"2026-08-11T17:42:36.556Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}