juicedata/juicefs · error

Cannot find WinFsp installation path from registry, please m

Error message

Cannot find WinFsp installation path from registry, please make sure WinFsp is installed correctly.

What it means

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.

Source

Thrown at pkg/winfsp/winfs.go:1450

	logger.Debug("Command line for juicefs service: ", strings.Join(cmds, " "))

	cmdLine := strings.Join(cmds, " ")

	winfspServiceName := "juicefs-" + alias
	if err := updateWinFspRegService(winfspServiceName, cmdLine, alias, logPath, asNetworkDrive); err != nil {
		return fmt.Errorf("Failed to update WinFsp service registry: %s", err)
	}

	// We need to use the "net use" for some users who have enabled the 'net use /persistent:yes' option for
	// auto-reconnecting after reboot.
	winFspBinPath := getWinFspBinPath()
	mountByNetUse := os.Getenv("JFS_WIN_MOUNT_VIA") != "winfsp-launchctl"
	if !asNetworkDrive {
		mountByNetUse = false
	}

	if winFspBinPath == "" && !mountByNetUse {
		return fmt.Errorf(`Cannot find WinFsp installation path from registry, please make sure WinFsp is installed correctly.`)
	}

	if !mountByNetUse {
		winfspLauncher := "launchctl-x64.exe"
		logger.Debugf("WinFsp Bin Path: %s", winFspBinPath)
		if winFspBinPath != "" {
			winfspLauncher = filepath.Join(winFspBinPath, winfspLauncher)
		}

		// the second param of start subcommand must be the same as the third param
		// or the Explorer will not be able to disconnect the volume.
		cmd := exec.Command(winfspLauncher, "start", winfspServiceName, alias, alias, mountpoint)
		cmd.Dir = winFspBinPath
		logger.Debugf("Mounting command(using launchctl): %s", cmd.String())

		out, err := cmd.CombinedOutput()
		if err != nil {
			return fmt.Errorf("Failed to mount juicefs as system service: %s, output: %s", err, string(out))

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Install (or reinstall) WinFsp from the official installer so the registry Install path is populated.
2. If you do not need launchctl mode, unset JFS_WIN_MOUNT_VIA=winfsp-launchctl so the 'net use' fallback can be used.
3. 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).
4. Re-run the mount after installation; confirm launchctl-x64.exe exists in the WinFsp bin directory.

Example fix

// before
set JFS_WIN_MOUNT_VIA=winfsp-launchctl
juicefs mount redis://... X:   // WinFsp missing
// after: install WinFsp, then
msiexec /i winfsp.msi /qn
juicefs mount redis://... X:

binPath := getWinFspBinPath()
if binPath == "" && os.Getenv("JFS_WIN_MOUNT_VIA") == "winfsp-launchctl" {
    return errors.New("WinFsp not installed: install it or unset JFS_WIN_MOUNT_VIA")
}
if _, err := os.Stat(filepath.Join(binPath, "launchctl-x64.exe")); err != nil { /* reinstall WinFsp */ }

if err := mount(...); strings.Contains(err.Error(), "Cannot find WinFsp installation path") { /* install WinFsp or switch to net use fallback */ }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Failed to create registry key: %s
• Failed to open registry key: %s
• Failed to set registry key: %s
• Failed to get current file path: %s
• Failed to delete registry key: %s

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/e2603c622c745786. Report an issue: GitHub.