What causes "macOS unmount failed with {status}" in astrid-runtime/astrid?

Find and close processes using the volume: lsof +D or sudo umount -f if safe

macOS unmount failed with {status}

Error message

macOS unmount failed with {status}

What it means

native_unmount runs /sbin/umount <mountpoint> and bails if the process reports failure, including the exit status in the message. A non-zero status means the kernel refused to unmount — the message shows the raw status (e.g. exit code 1/16) rather than a classified cause.

Source

Thrown at crates/astrid-storage-provider-fskit/src/main.rs:582

pub(crate) fn native_mount(
    lease: &StorageMountLeaseV1,
    mountpoint: &Path,
) -> std::future::Ready<Result<()>> {
    let _ = (lease, mountpoint);
    std::future::ready(Err(anyhow::anyhow!(
        "the FSKit provider is available only on macOS"
    )))
}

#[cfg(target_os = "macos")]
pub(crate) async fn native_unmount(mountpoint: &Path) -> Result<()> {
    let status = tokio::process::Command::new("/sbin/umount")
        .arg(mountpoint)
        .status()
        .await
        .context("invoke macOS unmount")?;
    if !status.success() {
        bail!("macOS unmount failed with {status}");
    }
    Ok(())
}

#[cfg(target_os = "macos")]
fn native_mount_is_active(mountpoint: &Path) -> Result<bool> {
    let status = nix::sys::statfs::statfs(mountpoint)
        .with_context(|| format!("inspect native mountpoint {}", mountpoint.display()))?;
    Ok(status.filesystem_type_name() == "astridfs")
}

#[cfg(not(target_os = "macos"))]
pub(crate) fn native_unmount(mountpoint: &Path) -> std::future::Ready<Result<()>> {
    let _ = mountpoint;
    std::future::ready(Err(anyhow::anyhow!(
        "the FSKit provider is available only on macOS"
    )))
}

View on GitHub (pinned to affd8760f4)

Solutions

Find and close processes using the volume: lsof +D <mountpoint> or sudo umount -f <mountpoint> if safe
Check whether the path is actually still mounted before unmounting (native_mount_is_active)
Retry after closing apps (Finder windows, terminals) that reference the volume
If the registry record is stale, remove/reconcile the record and unmount manually

Example fix

// before
unmount(&selector).await?; // "macOS unmount failed with exit status: 1"
// after
if native_mount_is_active(&mountpoint)? {
    close_open_handles(&mountpoint);
    unmount(&selector).await?;
}

Defensive patterns

Strategy: try-catch

Validate before calling

let active = native_mount_is_active(&mountpoint)?;
if !active { /* nothing to unmount; skip or reconcile record */ }

Try / catch

match unmount(&selector).await {
    Err(e) if e.to_string().contains("macOS unmount failed") => {
        // find blockers
        // lsof +D <mountpoint>; close Finder/terminal handles; retry once
    }
    r => r?,
}

Prevention

Close open files and shells with cwd under the mountpoint before unmounting
Check mount activity before attempting unmount to avoid stale records
Use `mount | grep` to confirm state on macOS
Implement a retry with backoff for transient EBUSY

When it happens

Trigger: Calling unmount (or rollback_after_native_failure, actual_fskit_mount_and_unmount_round_trip) on macOS when umount fails: files open on the volume, a process with cwd inside the mountpoint, or the mount no longer exists.

Common situations: Finder or a terminal holding the volume open; an editor or build daemon with cwd under the mountpoint; trying to unmount an already-unmounted path (stale registry record).

Related errors

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