astrid-runtime/astrid · error

mountpoint must be absolute

Error message

mountpoint must be absolute

What it means

validate_mountpoint_layout rejects any mountpoint path that is not absolute before any mount/unmount operation. Relative paths are ambiguous because the FSKit helper service may run with a different working directory than the caller, so the provider requires a fully-qualified path. The check runs on every mount, unmount, and validation path.

Source

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

            bail!(
                "mountpoint ancestor is writable without sticky protection: {}",
                path.display()
            );
        }
        ancestor = path.parent();
    }
    Ok(())
}

#[cfg(not(unix))]
fn validate_mountpoint_ancestors(mountpoint: &Path) -> Result<()> {
    let _ = mountpoint;
    Ok(())
}

fn validate_mountpoint_layout(mountpoint: &Path) -> Result<()> {
    if !mountpoint.is_absolute() {
        bail!("mountpoint must be absolute");
    }
    if mountpoint.components().any(|component| {
        matches!(
            component,
            std::path::Component::ParentDir | std::path::Component::CurDir
        )
    }) {
        bail!("mountpoint contains traversal: {}", mountpoint.display());
    }
    if mountpoint.parent().is_none() {
        bail!("mountpoint must be below a parent directory");
    }
    Ok(())
}

#[cfg(target_os = "macos")]
pub(crate) async fn native_mount(lease: &StorageMountLeaseV1, mountpoint: &Path) -> Result<()> {
    let output = tokio::process::Command::new("/sbin/mount")

View on GitHub (pinned to affd8760f4)

Solutions

1. Pass an absolute path such as /Volumes/fskit-mnt instead of a relative one
2. Canonicalize in the caller: std::fs::canonicalize or std::path::absolute before invoking the provider
3. If mounting a new empty dir, build the absolute path explicitly from root, e.g. PathBuf::from("/Volumes").join(name)

Example fix

// before
let mountpoint = Path::new("mnt/fskit");
// after
let mountpoint = std::path::absolute("mnt/fskit")?; // e.g. /work/mnt/fskit

fn ensure_absolute(mp: &std::path::Path) -> anyhow::Result<()> {
    anyhow::ensure!(mp.is_absolute(), "mountpoint must be absolute: {}", mp.display());
    Ok(())
}

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

When it happens

Trigger: Passing a relative path (e.g. "mnt/fs") as the mountpoint argument to mount, unmount, prepare_mountpoint, validate_mounted_mountpoint, or validate_unmounted_mountpoint.

Common situations: Building the mountpoint from a user-supplied CLI flag without canonicalizing it; calling the provider from a script whose cwd differs from the service's; forgetting to join a base directory with Path::join or abs_path.

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

• mountpoint must be below a parent directory
• mountpoint must be absolute
• mountpoint parent is not a directory: {}
• legacy capsule directory is not a regular directory: {}
• legacy capsule entry is not a regular directory: {}

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