{"record":{"id":"bbfb5e5a05d1d822","repo":"jdx/mise","slug":"failed-to-create-file-symlink-err","errorCode":null,"errorMessage":"failed to create file symlink: {err}","messagePattern":"failed to create file symlink: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/shims.rs","lineNumber":2813,"sourceCode":"            {\n                std::os::unix::fs::symlink(target, link)\n            }\n            #[cfg(windows)]\n            {\n                std::os::windows::fs::symlink_file(target, link)\n            }\n        };\n        match result {\n            Ok(()) => true,\n            Err(err)\n                if matches!(\n                    err.kind(),\n                    std::io::ErrorKind::PermissionDenied | std::io::ErrorKind::Unsupported\n                ) =>\n            {\n                false\n            }\n            Err(err) => panic!(\"failed to create file symlink: {err}\"),\n        }\n    }\n\n    /// A single-link mise layout: the PATH-visible `mise.exe` is a link, and\n    /// `mise-shim.exe` ships only beside the real binary. Returns the linked\n    /// mise and the real shim, or `None` when symlinks cannot be created on\n    /// this host.\n    fn single_link_layout(temp: &Path) -> Option<(PathBuf, PathBuf)> {\n        let real_dir = temp.join(\"real\").join(\"bin\");\n        let links_dir = temp.join(\"links\");\n        fs::create_dir_all(&real_dir).unwrap();\n        fs::create_dir_all(&links_dir).unwrap();\n        let real_mise = real_dir.join(\"mise.exe\");\n        fs::write(&real_mise, \"mise\").unwrap();\n        let real_shim = real_dir.join(\"mise-shim.exe\");\n        fs::write(&real_shim, \"mise-shim\").unwrap();\n        let linked_mise = links_dir.join(\"mise.exe\");\n        if !try_symlink_file(&real_mise, &linked_mise) {","sourceCodeStart":2795,"sourceCodeEnd":2831,"githubUrl":"https://github.com/jdx/mise/blob/afd2eddd3a50c16190efc1c7e94404b48f72af57/src/shims.rs#L2795-L2831","documentation":"On Windows 'file'-mode shim layouts, mise tries to create a file symlink for the shim; errors with kind PermissionDenied or Unsupported are treated as 'symlinks unavailable' (returns false), but any other I/O error triggers panic(\"failed to create file symlink: {err}\"). This is a fail-fast for unexpected filesystem failures during shim installation.","triggerScenarios":"std::os::windows::fs::symlink_file fails with an error other than PermissionDenied/Unsupported — e.g. the target directory does not exist, the path is invalid, or an antivirus/filesystem filter returns an exotic error — while creating shim links in single-link mise layouts.","commonSituations":"Shim directory removed or on a network/UNC drive mid-run; path too long (>260 chars) on Windows; shim target path occupied by a locked file; exotic filesystem (FAT/exFAT, Docker bind mount) that fails symlinks with unusual error kinds.","solutions":["Recreate the mise shim directory and run `mise reshim`","Check the underlying io error in the message and fix the specific cause (missing directory, invalid path, long path)","Enable Windows long-path support or shorten the install path if the error is path-length related","If symlinks are fundamentally unavailable in your environment, switch MISE_WINDOWS_SHIM_MODE to a supported mode instead of symlink mode"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Before relying on file symlinks on Windows, probe once:\nlet probe = dir.join(\".mise_symlink_probe\");\nlet symlinks_ok = std::os::windows::fs::symlink_file(std::env::current_exe().unwrap(), &probe).is_ok();\nlet _ = std::fs::remove_file(&probe);","typeGuard":null,"tryCatchPattern":"match std::os::windows::fs::symlink_file(&target, &link) {\n    Ok(()) => { /* proceed */ }\n    Err(e) if matches!(e.kind(), io::ErrorKind::PermissionDenied | io::ErrorKind::Unsupported) => { /* fall back to copy */ }\n    Err(e) => { /* treat all other errors as symlink-unavailable and fall back too */ }\n}","preventionTips":["Ensure the shim directory exists and is on a local NTFS volume before creating shims","Enable Windows Developer Mode or run elevated if symlink privileges are missing","Keep mise install paths short to avoid MAX_PATH issues","Fall back to copy-based shim mode when symlinks are unavailable"],"tags":["rust","windows","symlink","filesystem"],"backgroundTag":"permission-denied","analyzedSha":"afd2eddd3a50c16190efc1c7e94404b48f72af57","analyzedAt":"2026-09-09T01:38:25.179Z","contentChangedAt":"2026-09-09T01:38:25.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}