{"record":{"id":"a0b1e20e0dc0fbaa","repo":"astrid-runtime/astrid","slug":"the-winfsp-provider-is-available-only-on-windows","errorCode":null,"errorMessage":"the WinFsp provider is available only on Windows","messagePattern":"the WinFsp provider is available only on Windows","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-storage-provider-winfsp/src/main.rs","lineNumber":387,"sourceCode":"            return Err(error)\n                .with_context(|| format!(\"inspect mountpoint {}\", mountpoint.display()));\n        },\n        Ok(_) => bail!(\n            \"WinFsp directory mountpoint must not already exist: {}\",\n            mountpoint.display()\n        ),\n    }\n    // WinFsp creates and owns directory mountpoint leaves. Treat the leaf as\n    // provider-created so failure and unmount cleanup remain idempotent.\n    Ok((mountpoint, true))\n}\n\n#[cfg(not(windows))]\nfn prepare_mountpoint(\n    _requested: Option<PathBuf>,\n    _view: &astrid_core::storage_provider::StorageProviderViewV1,\n) -> Result<(PathBuf, bool)> {\n    bail!(\"the WinFsp provider is available only on Windows\")\n}\n\n#[cfg(windows)]\nfn first_free_drive() -> Result<PathBuf> {\n    for letter in b'D'..=b'Z' {\n        let root = PathBuf::from(format!(\"{}:\\\\\", letter as char));\n        match std::fs::metadata(&root) {\n            Ok(_) => {},\n            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {\n                return Ok(root);\n            },\n            Err(error) => {\n                return Err(error)\n                    .context(format!(\"inspect Windows drive target {}\", root.display()));\n            },\n        }\n    }\n    bail!(\"no free Windows drive target is available; specify a directory mountpoint\")","sourceCodeStart":369,"sourceCodeEnd":405,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-storage-provider-winfsp/src/main.rs#L369-L405","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before (Linux host config)\nstorage_provider = \"winfsp\"\n// after (Linux host config)\nstorage_provider = \"fuse\"","handlingStrategy":"fallback","validationCode":"// Gate provider selection on OS before invoking\nfn winfsp_available() -> bool {\n    cfg!(windows)\n}","typeGuard":null,"tryCatchPattern":"match provider.mount(request).await {\n    Err(e) if e.to_string().contains(\"available only on Windows\") => {\n        // fall back to a platform-appropriate provider\n        fuse_provider.mount(request).await\n    },\n    other => other,\n}","preventionTips":["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"],"tags":["platform","windows","unsupported-os","winfsp"],"backgroundTag":"unsupported-platform","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}