astrid-runtime/astrid · error

HOME must be absolute to choose a private mountpoint

Error message

HOME must be absolute to choose a private mountpoint

What it means

default_mountpoint() builds the fallback mount path as $HOME/Astrid/<principal>, requiring HOME to be set AND an absolute path; a relative HOME would produce a mountpoint that depends on the process cwd. This bail fires when HOME exists but is relative (e.g. 'home/user'). A missing HOME yields the sibling 'HOME is required' error instead.

Source

Thrown at crates/astrid-storage-provider-fskit/src/main.rs:460

    if existed {
        validate_unmounted_mountpoint(&mountpoint)?;
    } else {
        astrid_core::platform_fs::ensure_private_directory(&mountpoint)
            .with_context(|| format!("create private mountpoint {}", mountpoint.display()))?;
        validate_unmounted_mountpoint(&mountpoint)?;
    }
    Ok((mountpoint, !existed))
}

fn default_mountpoint(
    home: Option<std::ffi::OsString>,
    view: &astrid_core::storage_provider::StorageProviderViewV1,
) -> Result<PathBuf> {
    let home = home
        .map(PathBuf::from)
        .ok_or_else(|| anyhow::anyhow!("HOME is required to choose a private mountpoint"))?;
    if !home.is_absolute() {
        bail!("HOME must be absolute to choose a private mountpoint");
    }
    let leaf = match view {
        astrid_core::storage_provider::StorageProviderViewV1::Principal(principal) => {
            principal.to_string()
        },
        astrid_core::storage_provider::StorageProviderViewV1::Fleet(fleet) => fleet.to_string(),
        astrid_core::storage_provider::StorageProviderViewV1::Admin => "system".to_owned(),
    };
    Ok(home.join("Astrid").join(leaf))
}

fn validate_unmounted_mountpoint(mountpoint: &Path) -> Result<()> {
    validate_mountpoint_layout(mountpoint)?;
    validate_mountpoint_ancestors(mountpoint)?;
    astrid_core::platform_fs::verify_no_redirects(mountpoint)
        .with_context(|| format!("reject redirected mountpoint {}", mountpoint.display()))?;
    astrid_core::platform_fs::validate_private_directory(mountpoint)
        .with_context(|| format!("reject unsafe mountpoint {}", mountpoint.display()))?;

View on GitHub (pinned to affd8760f4)

Solutions

1. Set HOME to an absolute path (e.g. HOME=/root or HOME=/home/alice) before launching the provider.
2. Or pass an explicit absolute mountpoint in the mount request so default_mountpoint() is never consulted.
3. Fix the environment/unit file that exports a relative HOME.

Example fix

// before
HOME=./homedir astrid-fskit-provider
// after
HOME=/home/alice astrid-fskit-provider
# or request an explicit mountpoint in the mount request

fn home_is_usable() -> bool {
    std::env::var_os("HOME")
        .map(|h| PathBuf::from(&h).is_absolute())
        .unwrap_or(false)
}
// if false, pass an explicit absolute mountpoint in the request

fn valid_home(home: &Option<std::ffi::OsString>) -> bool {
    home.as_ref().map(|h| PathBuf::from(h).is_absolute()).unwrap_or(false)
}

match result {
    Err(e) if e.to_string().contains("HOME must be absolute") => {
        // fall back to explicit mountpoint or fix environment and retry
    },
    other => other,
}

When it happens

Trigger: No explicit mountpoint passed to the mount request and std::env::var_os("HOME") yields a value whose is_absolute() is false, so default_mountpoint() (via prepare_mountpoint) bails.

Common situations: Running the provider in a container, systemd unit, or CI where HOME is set to a relative or bogus value; shells with HOME='.' or '~/'; test harnesses overriding HOME incorrectly.

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_ENFORCED_DISTRO must not be empty
• ASTRID_HOME must be an absolute path
• neither ASTRID_HOME nor HOME environment variable is set
• 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/2834ebca4eed5767. Report an issue: GitHub.