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.

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
Defensive patterns

Strategy: validation

Validate before calling

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");
}

Type guard

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

Try / catch

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

Prevention

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

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

Appendix: 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)