astrid-runtime/astrid · error

WinFsp failed to start private mount: {status:#x}

Error message

WinFsp failed to start private mount: {status:#x}

What it means

Raised in `run_private_service` (crates/astrid-storage-provider-winfsp/src/win.rs:216) when `FileSystem::start` returns a non-success NTSTATUS after handing the callback filesystem and UTF-16 mountpoint to WinFsp. The status code is formatted in hex (`{status:#x}`). This means WinFsp refused to create the private mount — the volume could not be registered/mounted at the requested mountpoint.

Source

Thrown at crates/astrid-storage-provider-winfsp/src/win.rs:216

    }
    probe_callback(&launch).await?;
    let listener = local_transport::bind(&launch.control_path).with_context(|| {
        format!(
            "bind WinFsp service control {}",
            launch.control_path.display()
        )
    })?;
    let callback = CallbackFs::new(launch.lease.clone(), runtime)
        .map_err(|failure| anyhow::anyhow!("build WinFsp callback filesystem: {failure:?}"))?;
    initialize_winfsp()?;
    let mountpoint = U16CString::from_os_str(launch.mountpoint.as_os_str())
        .map_err(|_| anyhow::anyhow!("WinFsp mountpoint is not valid UTF-16"))?;
    let filesystem = FileSystem::start(
        volume_params(launch.lease.access),
        Some(&mountpoint),
        callback,
    )
    .map_err(|status| anyhow::anyhow!("WinFsp failed to start private mount: {status:#x}"))?;
    let ready = StorageProviderServiceReadyV1 {
        schema: STORAGE_FILESYSTEM_SERVICE_READY_SCHEMA_V1,
        provider: crate::PROVIDER_NAME.to_owned(),
        mount_id: launch.lease.mount_id.as_uuid(),
        control_path: launch.control_path.clone(),
        challenge,
    };
    let mut stdout = std::io::stdout().lock();
    serde_json::to_writer(&mut stdout, &ready).context("encode WinFsp readiness")?;
    stdout
        .write_all(b"\n")
        .context("terminate WinFsp readiness response")?;
    stdout.flush().context("flush WinFsp readiness")?;

    let result = private_service_loop(filesystem, listener, &launch).await;
    let _ = local_transport::remove_endpoint(&launch.control_path);
    result
}

View on GitHub (pinned to affd8760f4)

Solutions

1. Decode the hex NTSTATUS in the message (e.g. 0x80ffffff-range driver errors vs 0xC0000034 object-not-found) to identify the concrete mount failure.
2. Verify the mountpoint is free: no other volume or stale WinFsp mount is using that drive letter/directory.
3. Confirm WinFsp is installed and its driver is running (winfsp DLL co-located with the exe and the Fsp driver service started).
4. Check process privileges — mounting at a drive letter or public path may require elevation or matching access rights.
5. Pick a different mountpoint and retry the mount.

Example fix

// before
let filesystem = FileSystem::start(
    volume_params(launch.lease.access),
    Some(&mountpoint),
    callback,
)
.map_err(|status| anyhow::anyhow!("WinFsp failed to start private mount: {status:#x}"))?;
// after (pre-check mountpoint availability)
ensure_mountpoint_free(&launch.mountpoint).context("mountpoint availability precheck")?;
let filesystem = FileSystem::start(
    volume_params(launch.lease.access),
    Some(&mountpoint),
    callback,
)
.with_context(|| format!("WinFsp failed to start private mount at {:?} (status {status:#x})", launch.mountpoint))?;

// Pre-check the mountpoint before FileSystem::start
let mountpoint = launch.mountpoint.as_os_str().to_str().context("mountpoint not Unicode")?;
ensure!(!mountpoint.is_empty(), "mountpoint is empty");
// verify drive letter free / directory exists per platform APIs before mounting

fn mountpoint_usable(p: &std::path::Path) -> bool {
    p.to_str().is_some_and(|s| {
        (s.len() == 2 && s.as_bytes()[1] == b':')
            || std::path::Path::new(s).is_dir()
    })
}

let filesystem = FileSystem::start(params, Some(&mountpoint), callback)
    .map_err(|status| {
        error!(status = ?status, "WinFsp FileSystem::start failed");
        anyhow::anyhow!("WinFsp failed to start private mount: {status:#x}")
    })?;

When it happens

Trigger: Specifically: `FileSystem::start(volume_params(launch.lease.access), Some(&mountpoint), callback)` returns `Err(status)`. Typical statuses: the mountpoint drive letter is already in use, the mountpoint path does not exist or is invalid, WinFsp driver is not installed/started, or access restrictions forbid mounting.

Common situations: Another volume already occupies the requested drive letter; the mountpoint directory was deleted or locked before mount; WinFsp is not installed or its kernel driver failed to load; running without the privileges required for that mountpoint type; stale mount from a previous crashed session still holding the letter.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• no free Windows drive target is available; specify a directo
• WinFsp failed to start mount with status {status:#x}
• mountpoint must be absolute
• mountpoint parent is not a directory: {}
• WinFsp directory mountpoint must not already exist: {}

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