{"record":{"id":"f3f12654bc3d89fb","repo":"gitbutlerapp/gitbutler","slug":"failed-to-determine-home-directory","errorCode":null,"errorMessage":"Failed to determine home directory","messagePattern":"Failed to determine home directory","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/but-installer/src/config.rs","lineNumber":149,"sourceCode":"            bail!(\n                \"Too many arguments. Usage: but-installer [version|nightly] or GITBUTLER_VERSION=<version> but-installer\"\n            );\n        }\n\n        // Get version from CLI argument (takes precedence) or GITBUTLER_VERSION env var\n        let version_string = args\n            .get(1)\n            .cloned()\n            .or_else(|| env::var(\"GITBUTLER_VERSION\").ok());\n\n        let version_request = VersionRequest::from_string(version_string)?;\n        Self::new_with_version(version_request)\n    }\n\n    /// Create a new installer config with an explicit version request\n    pub(crate) fn new_with_version(version_request: VersionRequest) -> Result<Self> {\n        let home_dir =\n            dirs::home_dir().ok_or_else(|| anyhow!(\"Failed to determine home directory\"))?;\n\n        // Detect platform\n        let os = env::consts::OS;\n        let arch = env::consts::ARCH;\n\n        let platform = match (os, arch) {\n            (\"macos\", \"aarch64\") => \"darwin-aarch64\",\n            (\"macos\", \"x86_64\") => \"darwin-x86_64\",\n            (\"linux\", \"aarch64\") => \"linux-aarch64\",\n            (\"linux\", \"x86_64\") => \"linux-x86_64\",\n            (os, arch) => bail!(\"unsupported OS or architecture: {os} {arch}\"),\n        };\n\n        Ok(Self {\n            version_request,\n            home_dir,\n            platform: platform.to_string(),\n        })","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/gitbutlerapp/gitbutler/blob/58e5313667b857ef39a730e380af31816a7b1768/crates/but-installer/src/config.rs#L131-L167","documentation":"InstallerConfig::new_with_version() needs the user's home directory to build platform-specific install paths. The dirs::home_dir() crate returned None, so the installer cannot determine where to install and aborts.","triggerScenarios":"Calling InstallerConfig::new() or new_with_version() in an environment where the HOME environment variable is unset (Linux) or no profile directory is resolvable, so dirs::home_dir() returns None.","commonSituations":"Running the installer from a systemd service, cron job, or CI container with no HOME set; running as a system user without a home directory; stripped-down Docker images.","solutions":["Set the HOME environment variable to a writable directory (e.g. HOME=/root or HOME=/home/user)","Run the installer as a normal interactive user with a defined home directory","In containers, ensure the user entry in /etc/passwd has a valid home field"],"exampleFix":"// before\n./but-installer update\n// after\nHOME=/home/myuser ./but-installer update","handlingStrategy":"validation","validationCode":"if std::env::var_os(\"HOME\").is_none() {\n    anyhow::bail!(\"HOME is not set; installer cannot determine home directory\");\n}","typeGuard":null,"tryCatchPattern":"match InstallerConfig::new() {\n    Ok(cfg) => run(cfg),\n    Err(e) if e.to_string().contains(\"home directory\") => {\n        eprintln!(\"Set HOME and retry\"); std::process::exit(1);\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Ensure HOME is exported in services, cron, and CI containers","Avoid running installers as users without a home directory","Prefer invoking the installer from an interactive login shell"],"tags":["environment","home-directory","installer"],"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"}