{"record":{"id":"19aed8e46caf2fdb","repo":"astrid-runtime/astrid","slug":"native-mount-failure-message-classify-native-mount","errorCode":null,"errorMessage":"native_mount_failure_message(classify_native_mount_failure(output.status.code(), &stderr, &stdout))","messagePattern":"native_mount_failure_message\\(classify_native_mount_failure\\(output\\.status\\.code\\(\\), &stderr, &stdout\\)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-storage-provider-fskit/src/main.rs","lineNumber":556,"sourceCode":"        bail!(\"mountpoint must be below a parent directory\");\n    }\n    Ok(())\n}\n\n#[cfg(target_os = \"macos\")]\npub(crate) async fn native_mount(lease: &StorageMountLeaseV1, mountpoint: &Path) -> Result<()> {\n    let output = tokio::process::Command::new(\"/sbin/mount\")\n        .arg(\"-t\")\n        .arg(\"astridfs\")\n        .arg(&lease.resource_path)\n        .arg(mountpoint)\n        .output()\n        .await\n        .context(\"invoke macOS FSKit mount\")?;\n    if !output.status.success() {\n        let stderr = String::from_utf8_lossy(&output.stderr);\n        let stdout = String::from_utf8_lossy(&output.stdout);\n        bail!(native_mount_failure_message(\n            &classify_native_mount_failure(output.status.code(), &stderr, &stdout,)\n        ));\n    }\n    Ok(())\n}\n\n#[cfg(not(target_os = \"macos\"))]\npub(crate) fn native_mount(\n    lease: &StorageMountLeaseV1,\n    mountpoint: &Path,\n) -> std::future::Ready<Result<()>> {\n    let _ = (lease, mountpoint);\n    std::future::ready(Err(anyhow::anyhow!(\n        \"the FSKit provider is available only on macOS\"\n    )))\n}\n\n#[cfg(target_os = \"macos\")]","sourceCodeStart":538,"sourceCodeEnd":574,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-storage-provider-fskit/src/main.rs#L538-L574","documentation":"On macOS, native_mount invokes the FSKit mount helper as a subprocess; when it exits non-zero the error message embeds a classification of the failure (derived from exit code, stderr, and stdout) via classify_native_mount_failure. This means the OS-level mount syscall/helper refused the mount — the cause is reported inside the message, e.g. authorization, busy resource, or unknown filesystem.","triggerScenarios":"Calling mount (or actual_fskit_mount_and_unmount_round_trip) on macOS when the helper binary exits non-zero: missing entitlement/authorization, mountpoint already mounted, invalid lease/resource path, or FSKit extension not registered.","commonSituations":"Running without Full Disk Access or the required mount entitlement; attempting to mount the same volume twice; macOS security policies blocking FSKit extensions in CI VMs; stale registry record pointing at a gone resource.","solutions":["Read the classified cause embedded in the error message and address that specific issue (authorization, busy, not-found)","Verify the mountpoint is not already mounted: mount | grep <mountpoint>","Re-register/rebuild the FSKit extension and confirm it is enabled in System Settings > Login Items & Extensions","Re-run with the helper's stderr captured to see the raw OS error"],"exampleFix":"// before\nnative_mount(&lease, &mountpoint).await?; // fails, message shows classification\n// after\nmatch native_mount(&lease, &mountpoint).await {\n    Err(e) if e.to_string().contains(\"busy\") => { unmount_stale(&mountpoint)?; native_mount(&lease, &mountpoint).await? }\n    r => r?,\n}","handlingStrategy":"try-catch","validationCode":"// pre-flight: ensure helper exists and mountpoint is free\nif !std::path::Path::new(\"/sbin/mount_fskit\").exists() { /* helper missing */ }\nlet active = native_mount_is_active(&mountpoint).unwrap_or(false);\nif active { return Err(anyhow::anyhow!(\"already mounted\")); }","typeGuard":null,"tryCatchPattern":"match native_mount(&lease, &mp).await {\n    Err(e) => {\n        eprintln!(\"fskit mount failed: {e:#}\"); // classified cause is in the message\n        // handle authorization / busy / not-found per classification\n    }\n    Ok(()) => {}\n}","preventionTips":["Confirm FSKit extension is registered and enabled before mounting","Never mount the same volume twice; check active state first","Run on macOS with the required entitlements/Full Disk Access","Capture helper stderr for diagnostics"],"tags":["macos","fskit","mount","subprocess"],"backgroundTag":"command-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"}