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

ASTRID_HOME must be an absolute path

Error message

ASTRID_HOME must be an absolute path

What it means

Environment validation in AstridDirs::resolve_with_env: the ASTRID_HOME environment variable is set to a relative path (e.g. astrid-home instead of /abs/astrid-home). A relative home root would resolve against an unpredictable working directory and corrupt data placement, so the resolver returns an InvalidInput io error before any directory is created.

Source

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

        #[cfg(windows)]
        {
            Ok(Self {
                root: crate::platform_fs::default_astrid_home_root()?,
            })
        }

        #[cfg(not(windows))]
        {
            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",

View on GitHub (pinned to affd8760f4)

Solutions

1. Set ASTRID_HOME to an absolute path starting with '/'
2. Replace '~' with the expanded home directory before assigning the variable

Example fix

// before
export ASTRID_HOME=.astrid
// after
export ASTRID_HOME=/home/user/.astrid

if let Some(home) = std::env::var("ASTRID_HOME").ok().as_deref() {
    assert!(std::path::Path::new(home).is_absolute(), "ASTRID_HOME must be absolute");
}

fn absolute_env(v: &str) -> Option<std::path::PathBuf> {
    std::env::var(v).ok()
        .map(std::path::PathBuf::from)
        .filter(|p| p.is_absolute())
}

match dirs_result {
    Err(e) if e.kind() == io::ErrorKind::InvalidInput => {
        eprintln!("Set ASTRID_HOME to an absolute path");
    },
    other => other?,
}

When it happens

Trigger: Setting ASTRID_HOME to a relative path like '.astrid' or 'astrid-home' and calling the directory resolver (e.g. AstridDirs::resolve/prepare).

Common situations: Developers setting a relative override in .env or shell rc files, or using '~' assuming it gets expanded (expansion may not happen before PathBuf::from).

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• HOME must be an absolute path
• ASTRID_ENFORCED_DISTRO must not be empty
• workspace capsule component must be relative: {}
• HOME must be absolute to choose a private mountpoint
• {var_name} must not contain '..' path components

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