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

HOME must be an absolute path

Error message

HOME must be an absolute path

What it means

Environment validation in AstridDirs::resolve_with_env: ASTRID_HOME is unset and the HOME environment variable is set to a relative path. The home root must be absolute so capsule and state directories land in a stable location regardless of cwd; a relative HOME is rejected with an InvalidInput io error (distinct from the NotFound error raised when HOME is missing entirely).

Source

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

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

    /// Create from an explicit path (useful for testing).
    #[must_use]
    pub fn from_path(root: impl Into<PathBuf>) -> Self {
        Self { root: root.into() }
    }

    /// Validate the durable root without creating a parallel state tree.

View on GitHub (pinned to affd8760f4)

Solutions

1. Set HOME to an absolute path (e.g. /home/username)
2. Prefer setting ASTRID_HOME explicitly to a valid absolute path

Example fix

// before
export HOME=home
// after
export HOME=/home/user

if std::env::var("ASTRID_HOME").is_err() {
    if let Ok(home) = std::env::var("HOME") {
        assert!(std::path::Path::new(&home).is_absolute(), "HOME must be absolute");
    }
}

fn valid_home() -> Option<String> {
    std::env::var("HOME").ok().filter(|h| std::path::Path::new(h).is_absolute())
}

match dirs_result {
    Err(e) if e.kind() == io::ErrorKind::InvalidInput => {
        eprintln!("Fix HOME: must be an absolute path");
    },
    other => other?,
}

When it happens

Trigger: HOME set to a relative value (e.g. 'home' or '.') when ASTRID_HOME is unset, then invoking the directory resolver.

Common situations: Misconfigured container images, wrapper scripts that export HOME incorrectly, or running with env where HOME is a placeholder.

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

• ASTRID_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/c6d2f4a4c3febf4d. Report an issue: GitHub.