astrid-runtime/astrid · error

mountpoint must be absolute

Error message

mountpoint must be absolute

What it means

`prepare_mountpoint` validates the user-supplied mountpoint before handing it to WinFsp. On Windows, a mountpoint must be an absolute path (either a drive root like `E:\` or a directory path); a relative path cannot be resolved reliably for filesystem mounting, so the provider rejects it immediately. When no path is supplied, `first_free_drive` picks an absolute drive automatically and this error cannot occur.

Source

Thrown at crates/astrid-storage-provider-winfsp/src/main.rs:344

        {
            Ok(false)
        },
        AdminResponseBody::Error(error) => {
            bail!("kernel refused storage unmount authorization: {error}")
        },
        _ => bail!("kernel returned an unexpected storage unmount response"),
    }
}

#[cfg(windows)]
fn prepare_mountpoint(
    requested: Option<PathBuf>,
    view: &astrid_core::storage_provider::StorageProviderViewV1,
) -> Result<(PathBuf, bool)> {
    let _ = view;
    let mountpoint = requested.map_or_else(first_free_drive, Ok)?;
    if !mountpoint.is_absolute() {
        bail!("mountpoint must be absolute");
    }
    if is_drive_target(&mountpoint) {
        if std::fs::metadata(&mountpoint).is_ok() {
            bail!(
                "Windows drive target is already in use: {}",
                mountpoint.display()
            );
        }
        return Ok((mountpoint, false));
    }

    let parent = mountpoint
        .parent()
        .context("WinFsp directory mountpoint has no parent")?;
    std::fs::create_dir_all(parent)
        .with_context(|| format!("create mountpoint parent {}", parent.display()))?;
    astrid_core::platform_fs::verify_no_redirects(parent)
        .with_context(|| format!("reject redirected mountpoint parent {}", parent.display()))?;

View on GitHub (pinned to affd8760f4)

Solutions

1. Pass an absolute path (e.g. `C:\mounts\data` or a drive root `E:\`) as the mountpoint
2. Convert the requested path to absolute in the caller with `std::fs::canonicalize` or by joining with a known base directory
3. Omit the mountpoint argument entirely to let the provider auto-select the first free drive letter

Example fix

// before
let requested = Some(PathBuf::from("mnt/storage"));
mount(provider, requested).await?;
// after
let requested = Some(PathBuf::from("C:\\mnt\\storage"));
mount(provider, requested).await?;

// Rust caller-side pre-check
fn ensure_absolute_mountpoint(p: &std::path::Path) -> Result<(), String> {
    if p.is_absolute() { Ok(()) } else { Err(format!("mountpoint must be absolute: {}", p.display())) }
}

When it happens

Trigger: Calling `mount` (or code that invokes `directory_mountpoint_leaf_is_reserved_for_winfsp`/`prepare_mountpoint`) with `requested = Some(relative_path)` such as `Some(PathBuf::from("mnt/data"))` or `Some(PathBuf::from("..\\share"))`.

Common situations: Passing a CLI-relative directory argument to a mount command; scripts that build mount paths from the current working directory; configuration files storing relative mount paths.

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 parent is not a directory: {}
• mountpoint must be absolute
• mountpoint must be below a parent directory
• WinFsp directory mountpoint must not already exist: {}
• no free Windows drive target is available; specify a directo

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