astrid-runtime/astrid · error · std::io::Error::NotFound

HOME environment variable is not set

Error message

HOME environment variable is not set

What it means

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.

Source

Thrown at crates/astrid-cli/src/commands/self_update/path_setup.rs:22

//! state. An explicit `ASTRID_HOME` is an isolation boundary, so it must be
//! resolved before either side effect can happen; failure to classify it as
//! the default is a reason to do nothing, never a reason to guess.

use std::io;
use std::io::IsTerminal;
use std::path::{Path, PathBuf};

use crate::theme::Theme;

/// Return the account-level Astrid home used when `ASTRID_HOME` is absent.
pub(super) fn default_astrid_home_path() -> io::Result<PathBuf> {
    #[cfg(windows)]
    return astrid_core::platform_fs::default_astrid_home_root();

    #[cfg(not(windows))]
    {
        let home = std::env::var_os("HOME").ok_or_else(|| {
            io::Error::new(
                io::ErrorKind::NotFound,
                "HOME environment variable is not set",
            )
        })?;
        Ok(PathBuf::from(home).join(".astrid"))
    }
}

/// Decide whether this run may touch account-level PATH state.
///
/// An absent `ASTRID_HOME` means the runtime chose the account home. An
/// explicit path is allowed only when it equals that home exactly. Any other
/// explicit selection -- including an invalid or non-UTF-8 value -- stays a
/// private runtime home: return before creating `bin` or reading or writing a
/// shell profile.
pub(super) fn shell_profile_setup_wanted(
    astrid_home: Option<&Path>,
    default_home: Option<&Path>,

View on GitHub (pinned to affd8760f4)

Solutions

  1. Export HOME in the environment before running the CLI, e.g. HOME=/root astrid ...
  2. Fix the launching service definition (cron, systemd unit, Dockerfile) to set HOME
  3. In Docker, run with `docker run -e HOME=/root ...` or set ENV HOME in the image
  4. On Windows paths this is not applicable — astrid_core::platform_fs::default_astrid_home_root() is used instead

Example fix

// before (shell)
astrid chat   # fails: HOME not set
// after
HOME="$HOME" astrid chat   # or export HOME in your shell/systemd unit
Defensive patterns

Strategy: validation

Validate before calling

// Verify HOME is set before invoking the CLI
if std::env::var_os("HOME").is_none() {
    eprintln!("HOME is not set; cannot locate ~/.astrid");
    std::process::exit(1);
}

Try / catch

match ensure_path_setup() {
    Ok(()) => {},
    Err(e) if e.kind() == std::io::ErrorKind::NotFound
        && e.to_string().contains("HOME environment variable is not set") => {
        eprintln!("Set HOME (e.g. export HOME=/root) and retry.");
    }
    Err(e) => return Err(e.into()),
}

Prevention

When it happens

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

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

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 astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/8d7c7905c86aefe9. Report an issue: GitHub.