{"record":{"id":"8d7c7905c86aefe9","repo":"astrid-runtime/astrid","slug":"home-environment-variable-is-not-set","errorCode":null,"errorMessage":"HOME environment variable is not set","messagePattern":"HOME environment variable is not set","errorType":"exception","errorClass":"std::io::Error::NotFound","httpStatus":null,"severity":"error","filePath":"crates/astrid-cli/src/commands/self_update/path_setup.rs","lineNumber":22,"sourceCode":"//! state. An explicit `ASTRID_HOME` is an isolation boundary, so it must be\n//! resolved before either side effect can happen; failure to classify it as\n//! the default is a reason to do nothing, never a reason to guess.\n\nuse std::io;\nuse std::io::IsTerminal;\nuse std::path::{Path, PathBuf};\n\nuse crate::theme::Theme;\n\n/// Return the account-level Astrid home used when `ASTRID_HOME` is absent.\npub(super) fn default_astrid_home_path() -> io::Result<PathBuf> {\n    #[cfg(windows)]\n    return astrid_core::platform_fs::default_astrid_home_root();\n\n    #[cfg(not(windows))]\n    {\n        let home = std::env::var_os(\"HOME\").ok_or_else(|| {\n            io::Error::new(\n                io::ErrorKind::NotFound,\n                \"HOME environment variable is not set\",\n            )\n        })?;\n        Ok(PathBuf::from(home).join(\".astrid\"))\n    }\n}\n\n/// Decide whether this run may touch account-level PATH state.\n///\n/// An absent `ASTRID_HOME` means the runtime chose the account home. An\n/// explicit path is allowed only when it equals that home exactly. Any other\n/// explicit selection -- including an invalid or non-UTF-8 value -- stays a\n/// private runtime home: return before creating `bin` or reading or writing a\n/// shell profile.\npub(super) fn shell_profile_setup_wanted(\n    astrid_home: Option<&Path>,\n    default_home: Option<&Path>,","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-cli/src/commands/self_update/path_setup.rs#L4-L40","documentation":"default_astrid_home_path derives the ~/.astrid home directory from the HOME environment variable on non-Windows platforms. If HOME is unset, it cannot determine a user home and fails closed with this io::Error (ErrorKind::NotFound) rather than guessing a location. It is surfaced through ensure_path_setup during CLI startup.","triggerScenarios":"Calling default_astrid_home_path (via ensure_path_setup) on a Unix-like system when std::env::var_os(\"HOME\") returns None — i.e. HOME is unset or empty in the process environment.","commonSituations":"Running the CLI from cron/systemd where HOME is not exported; su/sudo environments that strip HOME; Docker containers started without -e HOME; running under service managers with a minimal environment.","solutions":["Export HOME in the environment before running the CLI, e.g. HOME=/root astrid ...","Fix the launching service definition (cron, systemd unit, Dockerfile) to set HOME","In Docker, run with `docker run -e HOME=/root ...` or set ENV HOME in the image","On Windows paths this is not applicable — astrid_core::platform_fs::default_astrid_home_root() is used instead"],"exampleFix":"// before (shell)\nastrid chat   # fails: HOME not set\n// after\nHOME=\"$HOME\" astrid chat   # or export HOME in your shell/systemd unit","handlingStrategy":"validation","validationCode":"// Verify HOME is set before invoking the CLI\nif std::env::var_os(\"HOME\").is_none() {\n    eprintln!(\"HOME is not set; cannot locate ~/.astrid\");\n    std::process::exit(1);\n}","typeGuard":null,"tryCatchPattern":"match ensure_path_setup() {\n    Ok(()) => {},\n    Err(e) if e.kind() == std::io::ErrorKind::NotFound\n        && e.to_string().contains(\"HOME environment variable is not set\") => {\n        eprintln!(\"Set HOME (e.g. export HOME=/root) and retry.\");\n    }\n    Err(e) => return Err(e.into()),\n}","preventionTips":["Set HOME explicitly in cron/systemd/Docker environments (Environment=HOME=..., docker -e HOME=...)","Avoid `sudo -i`-style commands that strip HOME when wrapping the CLI","Smoke-test CLI entry points under the same environment they run in production"],"tags":["environment","home","cli","filesystem"],"backgroundTag":"missing-env-var","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}