atuinsh/atuin · error

could not determine home directory

Error message

could not determine home directory

What it means

`home_dir()` resolves the user's home directory via the `directories` crate (`BaseDirs::new()`), which reads $HOME (or platform equivalents like getpwuid). It panics when no home directory can be determined at all. Nearly all Atuin config/data paths depend on this.

Solutions

1. Set the HOME environment variable (e.g. `export HOME=/home/user`) before running atuin
2. If using sudo, run `sudo -E` or configure sudo to preserve HOME
3. In containers, ensure the user exists in /etc/passwd (`useradd`) or set HOME explicitly
4. For systemd units, add `Environment=HOME=%h` or use a User= with a valid passwd entry

Example fix

// before
atuin sync   # fails: could not determine home directory
// after
export HOME="$(getent passwd "$(id -u)" | cut -d: -f6)"
atuin sync

// Pre-flight check before running atuin:
if std::env::var_os("HOME").map_or(true, |h| h.is_empty()) {
    eprintln!("HOME is not set; set it before running atuin");
    std::process::exit(1);
}

When it happens

Trigger: Calling `home_dir()` (directly or via `config_dir`, `data_dir`, `logs_dir`, `xdg_config_home`, `path`) when $HOME is unset and the passwd database has no entry for the current UID.

Common situations: Running atuin under systemd/supervisors with a sanitized environment missing $HOME; cron jobs without HOME set; `sudo -u otheruser` with env_reset; Docker containers running as a non-root UID absent from /etc/passwd.

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

• Could not build config
• Could not build default
• Could not deserialize config
• failed to create client
• failed to override timezone with UTC

AI-assisted analysis of atuinsh/atuin@c0c717ab04 (2026-09-12). Data as JSON: /api/errors/85f59324c8112c8b. Report an issue: GitHub.

Appendix: source

Thrown at crates/atuin-common/src/utils.rs:112

        // if .git is a file (worktree), resolve to the main repo root
        if let Some(main_repo) = resolve_git_worktree(&gitdir) {
            return Some(main_repo);
        }
        return Some(gitdir);
    }

    None
}

// TODO: more reliable, more tested
// I don't want to use ProjectDirs, it puts config in awkward places on
// mac. Data too. Seems to be more intended for GUI apps.

#[must_use]
pub fn home_dir() -> PathBuf {
    directories::BaseDirs::new()
        .map(|d| d.home_dir().to_path_buf())
        .expect("could not determine home directory")
}

/// Read an environment variable that must be nonempty.
///
/// This function will never return an empty string: if the environment variable is set but empty,
/// [`None`] is returned.
#[must_use]
pub fn env_nonempty(name: &str) -> Option<OsString> {
    std::env::var_os(name).filter(|value| !value.is_empty())
}

/// Read an environment variable that must be an absolute path.
///
/// This is usually done in the name of XDG-compliance which requires that paths given through
/// environment variables are absolute.
pub fn env_abspath(name: &str) -> Option<PathBuf> {
    env_nonempty(name).map(PathBuf::from).filter(|s| s.is_absolute())
}

View on GitHub (pinned to c0c717ab04)