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

{err}. Creating directory symlinks on Windows may require ad

Error message

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

What it means

On Windows, when mise creates a directory symlink whose target is a UNC (network) path, create_windows_unc_symlink calls std::os::windows::fs::symlink_dir. If that fails with PermissionDenied, the error is re-wrapped with this explanatory message: directory symlinks on Windows require either an elevated (administrator) process or Developer Mode enabled.

Source

Thrown at src/file.rs:944

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

#[cfg(windows)]

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

1. Enable Developer Mode: Settings > System > For developers > Developer Mode (lets non-admin processes create symlinks)
2. Run the terminal/shell as Administrator for the operation that creates the symlink
3. Move the mise data directory to a local disk (MISE_DATA_DIR / MISE_CACHE_DIR) so targets are not UNC paths

Example fix

# before (PowerShell, non-admin, Developer Mode off)
mise install node   # ...PermissionDenied: Creating directory symlinks on Windows may require administrator privileges or Developer Mode

# after
reg add 'HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' /v AllowDevelopmentWithoutDevLicense /t REG_DWORD /d 1 /f
# then retry in a new shell
mise install node

# PowerShell: check Developer Mode before mise operations that symlink
$dev = (Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -ErrorAction SilentlyContinue).AllowDevelopmentWithoutDevLicense
if (-not $dev -and -not ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
  Write-Error 'symlinks will fail: enable Developer Mode or run elevated'
}

Catch the io::Error whose message contains 'may require administrator privileges or Developer Mode'; retry once from an elevated shell, else fall back to locating data on a local drive instead of a UNC path.

When it happens

Trigger: A mise operation that symlinks a directory whose target lives on a network share (\\server\share\...) — e.g. the mise data/install directory redirected to a UNC path — while the process lacks the SeCreateSymbolicLinkPrivilege, so symlink_dir returns PermissionDenied.

Common situations: Corporate machines with Developer Mode disabled by policy; mise data dir or installs located on network drives; CI runners on Windows running non-elevated; fresh Windows install where Developer Mode was never turned on.

Related errors

• Unknown shim mode
• too many symlinks while resolving atomic write target: {}
• refusing to remove non-link: {}
• OCI system package layers with symlinks require a unix host
• refusing to replace non-file path: {}

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