What causes "Failed to determine home directory" in gitbutlerapp/gitbutler?

Set the HOME environment variable to a writable directory (e.g. HOME=/root or HOME=/home/user)

Failed to determine home directory

Error message

Failed to determine home directory

What it means

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.

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

Example fix

// before
./but-installer update
// after
HOME=/home/myuser ./but-installer update

Defensive patterns

Strategy: validation

Validate before calling

if std::env::var_os("HOME").is_none() {
    anyhow::bail!("HOME is not set; installer cannot determine home directory");
}

Try / catch

match InstallerConfig::new() {
    Ok(cfg) => run(cfg),
    Err(e) if e.to_string().contains("home directory") => {
        eprintln!("Set HOME and retry"); std::process::exit(1);
    }
    Err(e) => return Err(e),
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@58e5313667 (2026-09-18). Data as JSON: /api/errors/f3f12654bc3d89fb. Report an issue: GitHub.

Appendix: source

Thrown at crates/but-installer/src/config.rs:149

            bail!(
                "Too many arguments. Usage: but-installer [version|nightly] or GITBUTLER_VERSION=<version> but-installer"
            );
        }

        // Get version from CLI argument (takes precedence) or GITBUTLER_VERSION env var
        let version_string = args
            .get(1)
            .cloned()
            .or_else(|| env::var("GITBUTLER_VERSION").ok());

        let version_request = VersionRequest::from_string(version_string)?;
        Self::new_with_version(version_request)
    }

    /// Create a new installer config with an explicit version request
    pub(crate) fn new_with_version(version_request: VersionRequest) -> Result<Self> {
        let home_dir =
            dirs::home_dir().ok_or_else(|| anyhow!("Failed to determine home directory"))?;

        // Detect platform
        let os = env::consts::OS;
        let arch = env::consts::ARCH;

        let platform = match (os, arch) {
            ("macos", "aarch64") => "darwin-aarch64",
            ("macos", "x86_64") => "darwin-x86_64",
            ("linux", "aarch64") => "linux-aarch64",
            ("linux", "x86_64") => "linux-x86_64",
            (os, arch) => bail!("unsupported OS or architecture: {os} {arch}"),
        };

        Ok(Self {
            version_request,
            home_dir,
            platform: platform.to_string(),
        })

View on GitHub (pinned to 58e5313667)