{"record":{"id":"e2603c622c745786","repo":"juicedata/juicefs","slug":"cannot-find-winfsp-installation-path-from-registry","errorCode":null,"errorMessage":"Cannot find WinFsp installation path from registry, please make sure WinFsp is installed correctly.","messagePattern":"Cannot find WinFsp installation path from registry, please make sure WinFsp is installed correctly\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/winfsp/winfs.go","lineNumber":1450,"sourceCode":"\tlogger.Debug(\"Command line for juicefs service: \", strings.Join(cmds, \" \"))\n\n\tcmdLine := strings.Join(cmds, \" \")\n\n\twinfspServiceName := \"juicefs-\" + alias\n\tif err := updateWinFspRegService(winfspServiceName, cmdLine, alias, logPath, asNetworkDrive); err != nil {\n\t\treturn fmt.Errorf(\"Failed to update WinFsp service registry: %s\", err)\n\t}\n\n\t// We need to use the \"net use\" for some users who have enabled the 'net use /persistent:yes' option for\n\t// auto-reconnecting after reboot.\n\twinFspBinPath := getWinFspBinPath()\n\tmountByNetUse := os.Getenv(\"JFS_WIN_MOUNT_VIA\") != \"winfsp-launchctl\"\n\tif !asNetworkDrive {\n\t\tmountByNetUse = false\n\t}\n\n\tif winFspBinPath == \"\" && !mountByNetUse {\n\t\treturn fmt.Errorf(`Cannot find WinFsp installation path from registry, please make sure WinFsp is installed correctly.`)\n\t}\n\n\tif !mountByNetUse {\n\t\twinfspLauncher := \"launchctl-x64.exe\"\n\t\tlogger.Debugf(\"WinFsp Bin Path: %s\", winFspBinPath)\n\t\tif winFspBinPath != \"\" {\n\t\t\twinfspLauncher = filepath.Join(winFspBinPath, winfspLauncher)\n\t\t}\n\n\t\t// the second param of start subcommand must be the same as the third param\n\t\t// or the Explorer will not be able to disconnect the volume.\n\t\tcmd := exec.Command(winfspLauncher, \"start\", winfspServiceName, alias, alias, mountpoint)\n\t\tcmd.Dir = winFspBinPath\n\t\tlogger.Debugf(\"Mounting command(using launchctl): %s\", cmd.String())\n\n\t\tout, err := cmd.CombinedOutput()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to mount juicefs as system service: %s, output: %s\", err, string(out))","sourceCodeStart":1432,"sourceCodeEnd":1468,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/winfsp/winfs.go#L1432-L1468","documentation":"Thrown when the WinFsp installation directory could not be read from the Windows registry (getWinFspBinPath returned empty) AND the mount cannot fall back to the 'net use' path (either not a network drive, or JFS_WIN_MOUNT_VIA is set to winfsp-launchctl). The library needs launchctl-x64.exe from the WinFsp bin directory to start the service; without it, mounting as a service is impossible.","triggerScenarios":"Mounting as a system service when the WinFsp registry entries (Install/Memfs path under HKLM\\SOFTWARE\\WOW6432Node\\WinFsp) are missing — WinFsp not installed, a broken upgrade, 32/64-bit registry view mismatch, or mountByNetUse disabled while binPath is empty.","commonSituations":"WinFsp never installed or uninstalled; WinFsp installed per-user or in a nonstandard location not reflected in registry; running 32-bit binary on 64-bit Windows hitting WOW6432Node mismatch; setting JFS_WIN_MOUNT_VIA=winfsp-launchctl without WinFsp present.","solutions":["Install (or reinstall) WinFsp from the official installer so the registry Install path is populated.","If you do not need launchctl mode, unset JFS_WIN_MOUNT_VIA=winfsp-launchctl so the 'net use' fallback can be used.","Verify the registry value exists: check HKLM\\SOFTWARE\\WOW6432Node\\WinFsp for the install path (fix the 32/64-bit view if using a 32-bit build).","Re-run the mount after installation; confirm launchctl-x64.exe exists in the WinFsp bin directory."],"exampleFix":"// before\nset JFS_WIN_MOUNT_VIA=winfsp-launchctl\njuicefs mount redis://... X:   // WinFsp missing\n// after: install WinFsp, then\nmsiexec /i winfsp.msi /qn\njuicefs mount redis://... X:","handlingStrategy":"validation","validationCode":"binPath := getWinFspBinPath()\nif binPath == \"\" && os.Getenv(\"JFS_WIN_MOUNT_VIA\") == \"winfsp-launchctl\" {\n    return errors.New(\"WinFsp not installed: install it or unset JFS_WIN_MOUNT_VIA\")\n}\nif _, err := os.Stat(filepath.Join(binPath, \"launchctl-x64.exe\")); err != nil { /* reinstall WinFsp */ }","typeGuard":null,"tryCatchPattern":"if err := mount(...); strings.Contains(err.Error(), \"Cannot find WinFsp installation path\") { /* install WinFsp or switch to net use fallback */ }","preventionTips":["Install WinFsp via the official MSI before using service mounts","Only set JFS_WIN_MOUNT_VIA=winfsp-launchctl when WinFsp is present","Match binary bitness to the registry view (WOW6432Node)"],"tags":["windows","winfsp","registry","installation"],"backgroundTag":"missing-dependency","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}