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

neither ASTRID_HOME nor HOME environment variable is set

Error message

neither ASTRID_HOME nor HOME environment variable is set

What it means

Thrown by resolve_with_env when neither ASTRID_HOME nor HOME is present in the environment, so no home directory root can be determined. It is a NotFound error because a required environment input is missing.

Source

Thrown at crates/astrid-core/src/dirs.rs:299

            Self::resolve_with_env(None, std::env::var("HOME").ok())
        }
    }

    /// Internal resolver used to mock environment variables in tests securely.
    fn resolve_with_env(astrid_home: Option<String>, home: Option<String>) -> io::Result<Self> {
        let root = if let Some(custom) = astrid_home {
            let p = PathBuf::from(&custom);
            if !p.is_absolute() {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidInput,
                    "ASTRID_HOME must be an absolute path",
                ));
            }
            reject_parent_traversal(&p, "ASTRID_HOME")?;
            p
        } else {
            let home = home.ok_or_else(|| {
                io::Error::new(
                    io::ErrorKind::NotFound,
                    "neither ASTRID_HOME nor HOME environment variable is set",
                )
            })?;
            let home_path = PathBuf::from(&home);
            if !home_path.is_absolute() {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidInput,
                    "HOME must be an absolute path",
                ));
            }
            reject_parent_traversal(&home_path, "HOME")?;
            home_path.join(".astrid")
        };

        Ok(Self { root })
    }

View on GitHub (pinned to affd8760f4)

Solutions

1. Set ASTRID_HOME to an absolute path in the execution environment
2. Ensure HOME is exported for the user running the process
3. Fix the service/container definition so the env var is passed through

Example fix

// before: systemd unit without environment
[Service]
ExecStart=/usr/bin/astrid
// after
[Service]
Environment="HOME=/home/astrid"
ExecStart=/usr/bin/astrid

if std::env::var("ASTRID_HOME").is_err() && std::env::var("HOME").is_err() {
    std::env::set_var("ASTRID_HOME", "/var/lib/astrid");
}

fn has_home_env() -> bool {
    std::env::var("ASTRID_HOME").is_ok() || std::env::var("HOME").is_ok()
}

match dirs_result {
    Err(e) if e.kind() == io::ErrorKind::NotFound => {
        eprintln!("Set ASTRID_HOME or HOME before running");
    },
    other => other?,
}

When it happens

Trigger: Calling the directory resolver in an environment where both ASTRID_HOME and HOME are unset, e.g. stripped env in systemd services, cron, containers, or tests with cleared env.

Common situations: Running an Astrid CLI command under a service manager that purges the environment, Docker containers without HOME set, or CI jobs running with env -i.

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

• ASTRID_ENFORCED_DISTRO must not be empty
• HOME must be absolute to choose a private mountpoint
• ASTRID_HOME must be an absolute path
• HOME must be an absolute path
• invalid value for {capsule_id}.{key}: expected one of {}, go

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/01c6433a0932c3ec. Report an issue: GitHub.