What causes "the WinFsp provider is available only on Windows" in astrid-runtime/astrid?

Run this provider on Windows with the WinFSP driver installed (https://winfsp.dev)

the WinFsp provider is available only on Windows

Error message

the WinFsp provider is available only on Windows

What it means

The crate provides a `#[cfg(not(windows))]` stub of `prepare_mountpoint` that unconditionally fails: the WinFsp driver and its API only exist on Windows, so the provider cannot mount on any other platform. This gives a clear, actionable error instead of a link error or silent misbehavior when the provider is invoked on Linux/macOS.

Source

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

            return Err(error)
                .with_context(|| format!("inspect mountpoint {}", mountpoint.display()));
        },
        Ok(_) => bail!(
            "WinFsp directory mountpoint must not already exist: {}",
            mountpoint.display()
        ),
    }
    // WinFsp creates and owns directory mountpoint leaves. Treat the leaf as
    // provider-created so failure and unmount cleanup remain idempotent.
    Ok((mountpoint, true))
}

#[cfg(not(windows))]
fn prepare_mountpoint(
    _requested: Option<PathBuf>,
    _view: &astrid_core::storage_provider::StorageProviderViewV1,
) -> Result<(PathBuf, bool)> {
    bail!("the WinFsp provider is available only on Windows")
}

#[cfg(windows)]
fn first_free_drive() -> Result<PathBuf> {
    for letter in b'D'..=b'Z' {
        let root = PathBuf::from(format!("{}:\\", letter as char));
        match std::fs::metadata(&root) {
            Ok(_) => {},
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
                return Ok(root);
            },
            Err(error) => {
                return Err(error)
                    .context(format!("inspect Windows drive target {}", root.display()));
            },
        }
    }
    bail!("no free Windows drive target is available; specify a directory mountpoint")

View on GitHub (pinned to affd8760f4)

Solutions

Run this provider on Windows with the WinFSP driver installed (https://winfsp.dev)
Switch the storage provider selection to a platform-appropriate implementation (e.g. FUSE-based provider on Linux/macOS)
Gate provider selection in your configuration on the target OS so winfsp is never chosen on non-Windows hosts

Example fix

// before (Linux host config)
storage_provider = "winfsp"
// after (Linux host config)
storage_provider = "fuse"

Defensive patterns

Strategy: fallback

Validate before calling

// Gate provider selection on OS before invoking
fn winfsp_available() -> bool {
    cfg!(windows)
}

Try / catch

match provider.mount(request).await {
    Err(e) if e.to_string().contains("available only on Windows") => {
        // fall back to a platform-appropriate provider
        fuse_provider.mount(request).await
    },
    other => other,
}

Prevention

Select the storage provider based on target OS at startup
Exclude winfsp provider builds from Linux/macOS deployment artifacts
Document platform requirements in deployment configs

When it happens

Trigger: Running the astrid-storage-provider-winfsp binary (or invoking its `mount` path) on a non-Windows platform, where the cfg-stubbed `prepare_mountpoint` is compiled in and immediately bails.

Common situations: Deploying the WinFsp provider in a Linux container or CI runner; a cross-platform config that selects the winfsp provider regardless of OS; testing provider dispatch on a dev machine running macOS/Linux.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

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