astrid-runtime/astrid · error

no free Windows drive target is available; specify a directo

Error message

no free Windows drive target is available; specify a directory mountpoint

What it means

first_free_drive scans candidate drive-letter targets and bails when none of them is a usable free Windows drive target. The library refuses to silently pick or reuse a letter; it requires the caller to supply an explicit directory mountpoint instead. This keeps drive-letter assignment deterministic and user-controlled.

Source

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

    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")
}

#[cfg(windows)]
fn is_drive_target(path: &Path) -> bool {
    let Some(text) = path.to_str() else {
        return false;
    };
    let bytes = text.as_bytes();
    bytes.len() == 3
        && bytes[0].is_ascii_alphabetic()
        && bytes[1] == b':'
        && (bytes[2] == b'\\' || bytes[2] == b'/')
}

#[cfg(windows)]
async fn native_mount(lease: &StorageMountLeaseV1, mountpoint: &Path) -> Result<()> {
    win::spawn_daemon(lease, mountpoint).await
}

View on GitHub (pinned to affd8760f4)

Solutions

1. Pass an explicit directory mountpoint (e.g. C:\mounts\astrid) instead of relying on automatic drive-letter selection
2. Free a drive letter: unmap unused network drives (net use X: /delete) or remove subst mappings
3. Check which letters are taken with `net use` / Disk Management and confirm at least one candidate is free
4. Inspect the wrapped error context ('inspect Windows drive target ...') to see which candidate failed and why

Example fix

// before
let opts = MountOptions { mountpoint: None, .. };
provider.mount(opts)?; // picks a drive letter, fails when none free
// after
let opts = MountOptions { mountpoint: Some(PathBuf::from("C:\\mounts\\astrid")), .. };
provider.mount(opts)?;

fn ensure_mount_target_ok(mp: &Path) -> Result<(), String> {
    if mp.is_dir() { return Ok(()); }
    let letter = mp.to_str().ok_or("mountpoint not valid UTF-8")?;
    let drive = letter.trim_end_matches('\\');
    if drive.len() == 2 && drive.as_bytes()[1] == b':' && std::fs::metadata(drive).is_err() {
        return Ok(()); // free drive letter
    }
    Err("no free drive letter; pass an explicit directory mountpoint".into())
}

fn is_free_drive_designator(s: &str) -> bool {
    let b = s.as_bytes();
    b.len() == 2 && b[1] == b':' && std::fs::metadata(&s[..2]).is_err()
}

match provider.mount(opts) {
    Err(e) if e.to_string().contains("no free Windows drive target") => {
        mount_with_directory_fallback(opts)?;
    }
    other => other?,
}

When it happens

Trigger: Calling the WinFsp provider for a drive-letter mount when every candidate drive letter is already mapped, is not a valid drive target (is_drive_target fails), or cannot be inspected (stat on the root fails for all candidates).

Common situations: Machines with many mapped network drives or subst/DevDrive letters consuming most of A-Z; running in containers or CI where drive enumeration returns nothing; passing a drive-letter mount config on a system with no free letters.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• WinFsp failed to start private mount: {status:#x}
• mountpoint must be absolute
• mountpoint parent is not a directory: {}
• WinFsp directory mountpoint must not already exist: {}
• WinFsp mountpoint is not a directory: {}

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