{"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/0e07a155371a6ce88ae53a2c00df940280c09a67/crates/home/src/env.rs#L61-L97","documentation":"Returned by `cargo_home_with_cwd_env` (crates/home/src/env.rs:79) when `CARGO_HOME` is unset/empty AND `home_dir_with_env` returns `None`. Cargo needs a writable home base (`~/.cargo`) for its registry cache, git checkouts, and config; with no home directory resolvable it cannot proceed and raises this io::Error.","triggerScenarios":"`CARGO_HOME` is not set (or empty) and the OS reports no home directory — `std::env::home_dir()` returns `None`. Common in containers/CI running as a user with no passwd entry, or in sandboxed daemons.","commonSituations":"Docker images running cargo as a UID with no `/etc/passwd` entry; `HOME` unset in systemd units or cron; minimal scratch containers; chroot/nobody-user builds; hardened sandboxes that strip `HOME`.","solutions":["Set `CARGO_HOME` to an absolute, writable path before invoking cargo (e.g. `export CARGO_HOME=/tmp/cargo-home`).","Set `HOME` to a valid, writable directory so `home_dir()` resolves.","For containers, ensure the runtime user has a passwd entry (`useradd`) or run with a real home dir."],"exampleFix":"# before — container with no HOME / passwd entry\nRUN cargo build\n# after\nENV CARGO_HOME=/usr/local/cargo\nRUN mkdir -p $CARGO_HOME && cargo build","handlingStrategy":"validation","validationCode":"fn cargo_home_resolvable() -> bool {\n    std::env::var_os(\"CARGO_HOME\").filter(|s| !s.is_empty()).is_some() || std::env::home_dir().is_some()\n}\n// assert cargo_home_resolvable() before running cargo","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set CARGO_HOME (or HOME) in containers and CI.","Give the build user a real passwd entry.","Fail fast in CI setup if neither env var is present."],"tags":["cargo","environment","home","cargo-home","container"],"analyzedSha":"0e07a155371a6ce88ae53a2c00df940280c09a67","analyzedAt":"2026-08-06T01:46:58.334Z","schemaVersion":2}