{"record":{"id":"751123118f6f055d","repo":"astrid-runtime/astrid","slug":"winfsp-failed-to-start-private-mount-status-x","errorCode":null,"errorMessage":"WinFsp failed to start private mount: {status:#x}","messagePattern":"WinFsp failed to start private mount: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-storage-provider-winfsp/src/win.rs","lineNumber":216,"sourceCode":"    }\n    probe_callback(&launch).await?;\n    let listener = local_transport::bind(&launch.control_path).with_context(|| {\n        format!(\n            \"bind WinFsp service control {}\",\n            launch.control_path.display()\n        )\n    })?;\n    let callback = CallbackFs::new(launch.lease.clone(), runtime)\n        .map_err(|failure| anyhow::anyhow!(\"build WinFsp callback filesystem: {failure:?}\"))?;\n    initialize_winfsp()?;\n    let mountpoint = U16CString::from_os_str(launch.mountpoint.as_os_str())\n        .map_err(|_| anyhow::anyhow!(\"WinFsp mountpoint is not valid UTF-16\"))?;\n    let filesystem = FileSystem::start(\n        volume_params(launch.lease.access),\n        Some(&mountpoint),\n        callback,\n    )\n    .map_err(|status| anyhow::anyhow!(\"WinFsp failed to start private mount: {status:#x}\"))?;\n    let ready = StorageProviderServiceReadyV1 {\n        schema: STORAGE_FILESYSTEM_SERVICE_READY_SCHEMA_V1,\n        provider: crate::PROVIDER_NAME.to_owned(),\n        mount_id: launch.lease.mount_id.as_uuid(),\n        control_path: launch.control_path.clone(),\n        challenge,\n    };\n    let mut stdout = std::io::stdout().lock();\n    serde_json::to_writer(&mut stdout, &ready).context(\"encode WinFsp readiness\")?;\n    stdout\n        .write_all(b\"\\n\")\n        .context(\"terminate WinFsp readiness response\")?;\n    stdout.flush().context(\"flush WinFsp readiness\")?;\n\n    let result = private_service_loop(filesystem, listener, &launch).await;\n    let _ = local_transport::remove_endpoint(&launch.control_path);\n    result\n}","sourceCodeStart":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-storage-provider-winfsp/src/win.rs#L198-L234","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Decode the hex NTSTATUS in the message (e.g. 0x80ffffff-range driver errors vs 0xC0000034 object-not-found) to identify the concrete mount failure.","Verify the mountpoint is free: no other volume or stale WinFsp mount is using that drive letter/directory.","Confirm WinFsp is installed and its driver is running (winfsp DLL co-located with the exe and the Fsp driver service started).","Check process privileges — mounting at a drive letter or public path may require elevation or matching access rights.","Pick a different mountpoint and retry the mount."],"exampleFix":"// before\nlet filesystem = FileSystem::start(\n    volume_params(launch.lease.access),\n    Some(&mountpoint),\n    callback,\n)\n.map_err(|status| anyhow::anyhow!(\"WinFsp failed to start private mount: {status:#x}\"))?;\n// after (pre-check mountpoint availability)\nensure_mountpoint_free(&launch.mountpoint).context(\"mountpoint availability precheck\")?;\nlet filesystem = FileSystem::start(\n    volume_params(launch.lease.access),\n    Some(&mountpoint),\n    callback,\n)\n.with_context(|| format!(\"WinFsp failed to start private mount at {:?} (status {status:#x})\", launch.mountpoint))?;","handlingStrategy":"validation","validationCode":"// Pre-check the mountpoint before FileSystem::start\nlet mountpoint = launch.mountpoint.as_os_str().to_str().context(\"mountpoint not Unicode\")?;\nensure!(!mountpoint.is_empty(), \"mountpoint is empty\");\n// verify drive letter free / directory exists per platform APIs before mounting","typeGuard":"fn mountpoint_usable(p: &std::path::Path) -> bool {\n    p.to_str().is_some_and(|s| {\n        (s.len() == 2 && s.as_bytes()[1] == b':')\n            || std::path::Path::new(s).is_dir()\n    })\n}","tryCatchPattern":"let filesystem = FileSystem::start(params, Some(&mountpoint), callback)\n    .map_err(|status| {\n        error!(status = ?status, \"WinFsp FileSystem::start failed\");\n        anyhow::anyhow!(\"WinFsp failed to start private mount: {status:#x}\")\n    })?;","preventionTips":["Check drive-letter/directory availability before each mount and clean up stale mounts from prior crashed sessions.","Ensure WinFsp runtime (DLL + driver service) is installed and started on the host.","Run the mount with the privileges required for the chosen mountpoint type.","Log the NTSTATUS in hex alongside the mountpoint for fast triage."],"tags":["winfsp","mount","windows","ntstatus","filesystem"],"backgroundTag":"api-request-failed","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"}