astrid-runtime/astrid · error

mountpoint must be absolute

Error message

mountpoint must be absolute

What it means

prepare_mountpoint validates that the requested mountpoint path is absolute before creating anything. A relative path is rejected with "mountpoint must be absolute" (crates/astrid-storage-provider-fuse/src/mountpoint.rs:28).

Solutions

  1. Convert the path to absolute before mounting (std::fs::canonicalize or join with a base directory)
  2. Pass a fully-qualified path on the command line or in config
  3. Check the path with Path::is_absolute() before calling the mount API

Example fix

// before
let mp = PathBuf::from("mnt/vol");
prepare_mountpoint(mp)?; // bails: mountpoint must be absolute
// after
let mp = std::fs::canonicalize("mnt/vol")?; // or PathBuf::from("/home/user/mnt/vol")
prepare_mountpoint(mp)?;
Defensive patterns

Strategy: validation

Validate before calling

fn ensure_absolute(p: &std::path::Path) -> std::io::Result<std::path::PathBuf> { if p.is_absolute() { Ok(p.to_path_buf()) } else { std::fs::canonicalize(p) } }

Type guard

fn is_absolute_path(p: &str) -> bool { std::path::Path::new(p).is_absolute() }

Try / catch

match prepare_mountpoint(&mp) { Err(e) if e.to_string() == "mountpoint must be absolute" => prepare_mountpoint(&std::fs::canonicalize(&mp)?)?, r => r? }

Prevention

When it happens

Trigger: Calling prepare_mountpoint (directly or via the mount flow) with a relative path such as "mnt/vol" or "./vol" instead of an absolute path like "/home/user/Astrid/vol".

Common situations: Passing a CLI argument or config value as a relative path; relying on the process's current working directory; scripts invoked from unexpected directories.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at crates/astrid-storage-provider-fuse/src/mountpoint.rs:28

/// Prepare a canonical, private, empty, non-redirected Linux mountpoint.
pub(crate) fn prepare_mountpoint(
    requested: Option<PathBuf>,
    view: &StorageProviderViewV1,
) -> Result<(PathBuf, bool)> {
    let requested = requested.unwrap_or_else(|| {
        let leaf = match view {
            StorageProviderViewV1::Principal(principal) => principal.to_string(),
            StorageProviderViewV1::Fleet(fleet) => fleet.to_string(),
            StorageProviderViewV1::Admin => "system".to_owned(),
        };
        std::env::var_os("HOME")
            .map_or_else(|| PathBuf::from("/tmp"), PathBuf::from)
            .join("Astrid")
            .join(leaf)
    });
    if !requested.is_absolute() {
        bail!("mountpoint must be absolute");
    }
    let existed = requested.symlink_metadata().is_ok();
    if !existed {
        std::fs::create_dir_all(&requested)
            .with_context(|| format!("create mountpoint {}", requested.display()))?;
    }
    astrid_core::platform_fs::verify_no_redirects(&requested)
        .with_context(|| format!("reject redirected mountpoint {}", requested.display()))?;
    let metadata = std::fs::symlink_metadata(&requested)?;
    if !metadata.is_dir() {
        bail!("mountpoint is not a directory: {}", requested.display());
    }
    let expected_uid = u32::from(getuid());
    if metadata.uid() != expected_uid {
        bail!(
            "mountpoint must be owned by the current OS user: {}",
            requested.display()
        );

View on GitHub (pinned to affd8760f4)