jdx/mise · error · std::io::Error

. Creating directory symlinks on Windows may require…

Error message

{err}. Creating directory symlinks on Windows may require administrator privileges or Developer Mode

What it means

On Windows, `create_windows_unc_symlink` calls `std::os::windows::fs::symlink_dir`. When that fails with `PermissionDenied`, mise enriches the io error with guidance: creating directory symlinks on Windows requires either administrator privileges or Developer Mode to be enabled. The enriched error is then propagated by `create_windows_dir_link`.

Solutions

Enable Developer Mode: Settings → Update & Security → For developers → Developer Mode (allows symlink creation without elevation).
Re-run the mise command from an elevated (Administrator) terminal.
Grant the account the SeCreateSymbolicLinkPrivilege via secpol/Group Policy, or use a mise setting that avoids symlinks (e.g. copy/shim strategy).

Defensive patterns

Strategy: try-catch

Validate before calling

// Windows: check privilege before linking
let test_link = std::env::temp_dir().join("mise-symlink-probe");
let _ = std::fs::remove_file(&test_link);
if std::os::windows::fs::symlink_dir("C:\\Windows", &test_link).is_err() {
    eprintln!("symlink creation unavailable: enable Developer Mode or run elevated");
}

Try / catch

match create_windows_dir_link(target, link) {
    Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
        eprintln!("enable Developer Mode or run as Administrator, then retry");
    }
    other => other?,
}

Prevention

Enable Windows Developer Mode before using tools that symlink directories.
Run installation commands from an elevated shell when Developer Mode is off.
Prefer mise settings that avoid symlinks on restricted machines.

When it happens

Trigger: Calling file-link creation (e.g. symlinking an installed tool into a bin dir) on Windows without elevated rights or Developer Mode, so `symlink_dir(target, link)` returns `ErrorKind::PermissionDenied`.

Common situations: Regular (non-admin) user without Developer Mode running `mise install` for a tool that uses directory symlinks; restricted corporate laptop policy; running in a service account without the SeCreateSymbolicLinkPrivilege.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/3c62e15df9e2a7de. Report an issue: GitHub.

Appendix: source

Thrown at src/file.rs:1067

}

#[cfg(windows)]
pub(crate) fn is_unc_path(path: &Path) -> bool {
    matches!(
        path.components().next(),
        Some(std::path::Component::Prefix(prefix))
            if matches!(
                prefix.kind(),
                std::path::Prefix::UNC(..) | std::path::Prefix::VerbatimUNC(..)
            )
    )
}

#[cfg(windows)]
fn create_windows_unc_symlink(target: &Path, link: &Path) -> std::io::Result<()> {
    std::os::windows::fs::symlink_dir(target, link).map_err(|err| {
        if err.kind() == std::io::ErrorKind::PermissionDenied {
            std::io::Error::new(
                err.kind(),
                format!(
                    "{err}. Creating directory symlinks on Windows may require administrator privileges or Developer Mode"
                ),
            )
        } else {
            err
        }
    })
}

#[cfg(windows)]
fn create_windows_dir_link(target: &Path, link: &Path) -> std::io::Result<()> {
    if is_unc_path(target) {
        create_windows_unc_symlink(target, link)
    } else {
        junction::create(target, link)
    }

View on GitHub (pinned to 533346cc37)