{"record":{"id":"1f8e8f1e74dedba8","repo":"gitbutlerapp/gitbutler","slug":"could-not-determine-home-directory","errorCode":null,"errorMessage":"Could not determine home directory","messagePattern":"Could not determine home directory","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/but/src/command/agent/plan.rs","lineNumber":271,"sourceCode":"}\n\n#[derive(Debug, Clone)]\npub(super) struct InstructionWritePlan {\n    pub(super) path: PathBuf,\n    pub(super) agents: Vec<AgentTarget>,\n}\n\npub(super) fn collect_skill_installs(\n    agents: &[AgentTarget],\n    scope: Scope,\n    repo: Option<&RepoInfo>,\n) -> Result<Vec<SkillInstallPlan>> {\n    // Resolve each concrete install location (a single-location scope) to its\n    // base directory once, expanding `Both` into global + repository.\n    let mut locations: Vec<(Scope, PathBuf)> = Vec::new();\n    if matches!(scope, Scope::Global | Scope::Both) {\n        let home = but_path::home_dir()\n            .ok_or_else(|| anyhow::anyhow!(\"Could not determine home directory\"))?;\n        locations.push((Scope::Global, home));\n    }\n    if matches!(scope, Scope::Repository | Scope::Both) {\n        let root = repo\n            .map(|repo| repo.root.clone())\n            .context(\"Repository skill install requested outside a repository\")?;\n        locations.push((Scope::Repository, root));\n    }\n\n    let mut installs = Vec::new();\n    for agent in agents {\n        for (location, base_dir) in &locations {\n            if let Some(components) = agent.skill_path_components(*location) {\n                installs.push(SkillInstallPlan {\n                    agent: *agent,\n                    path: join_components(base_dir, components),\n                });\n            }","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/gitbutlerapp/gitbutler/blob/58e5313667b857ef39a730e380af31816a7b1768/crates/but/src/command/agent/plan.rs#L253-L289","documentation":"Raised in `collect_skill_installs` (crates/but/src/command/agent/plan.rs:271) when a skill install scope includes the global location (`Scope::Global` or `Scope::Both`) but `but_path::home_dir()` returns `None`, so the global base directory cannot be resolved.","triggerScenarios":"Running `but agent plan` (or related skill-install commands) with a global scope on a system where the HOME environment variable is unset and no platform home-directory API succeeds.","commonSituations":"Running in a stripped container/CI environment without HOME set; running as a system service with no user context; Windows deployments missing USERPROFILE; minimal Docker images.","solutions":["Set the HOME environment variable to a writable directory before running the command","On Windows ensure USERPROFILE is set; on systemd services set HOME=/root or the service user's home","Use a repository-only scope (avoid Global/Both) if a home directory is not needed","In containers, run as a user with a defined home (`useradd -m`) or export HOME in the entrypoint"],"exampleFix":"// before\nbut agent plan --scope both   # fails if HOME unset\n// after\nexport HOME=/home/user\nbut agent plan --scope both","handlingStrategy":"validation","validationCode":"if std::env::var_os(\"HOME\").is_none() && std::env::var_os(\"USERPROFILE\").is_none() {\n    return Err(\"set HOME (or USERPROFILE on Windows) before running skill install commands\");\n}","typeGuard":null,"tryCatchPattern":"match plan::collect_skill_installs(repo.as_ref(), scope) {\n    Err(e) if e.to_string().contains(\"Could not determine home directory\") => Err(\"set HOME and retry\"),\n    other => other,\n}","preventionTips":["Always export HOME in containers, CI jobs, and service units","Run CLI tools as a user with a defined home directory","Prefer repository-scoped installs in headless environments"],"tags":["environment","home-directory","config"],"backgroundTag":"missing-env-var","analyzedSha":"58e5313667b857ef39a730e380af31816a7b1768","analyzedAt":"2026-09-18T06:50:32.052Z","contentChangedAt":"2026-09-18T06:50:32.052Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}