juicedata/juicefs · error

Failed to mount juicefs as system service: %s, output: %s

Error message

Failed to mount juicefs as system service: %s, output: %s

What it means

Thrown when the launchctl-x64.exe start command for the registered juicefs WinFsp service exits non-zero. The error includes the launcher's combined stdout/stderr output so the underlying launcher failure (bad service registration, launcher error, port/permission issue) can be diagnosed.

Source

Thrown at pkg/winfsp/winfs.go:1468

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

		if !checkIfMountProcessReady(mountpoint, 25) {
			return fmt.Errorf("Mount command succeeded, but the mountpoint %s did not become ready in %d seconds, please check the juicefs logs for more information.", mountpoint, 25)
		}
	} else {
		logger.Debugf("Trying to start juicefs service by 'net use' command.")
		cmd := exec.Command("net", "use", mountpoint, fmt.Sprintf("\\\\%s\\%s", winfspServiceName, alias), "/Y")
		out, err := cmd.CombinedOutput()
		if err != nil {
			return fmt.Errorf("Failed to start juicefs service by 'net use': %s, output: %s", err, string(out))
		}
	}

	logger.Info("Juicefs mount process started successfully.")

	return nil
}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Inspect the 'output:' portion of the message — it contains launchctl's actual failure reason.
2. Re-register the service by re-running the mount command; if a stale service exists, remove it first (launchctl-x64.exe stop/delete or reinstall WinFsp).
3. Reboot after a fresh WinFsp install so the WinFsp driver is loaded, then retry.
4. Free the target drive letter/mountpoint if another process holds it, and retry.

Example fix

// before
launchctl-x64.exe start juicefs-myjfs ... // exit 1: service not found
// after: re-run mount to re-register, then verify
> juicefs mount redis://... X:
> launchctl-x64.exe list

// ensure service is registered and launcher binary exists before starting
if _, err := os.Stat(filepath.Join(winFspBinPath, "launchctl-x64.exe")); err != nil { return err }
if _, err := registry.OpenKey(registry.LOCAL_MACHINE, `SOFTWARE\WOW6432Node\WinFsp\Services\juicefs-<alias>`, registry.QUERY_VALUE); err != nil { return errors.New("service not registered; re-run mount") }

out, err := cmd.CombinedOutput()
if err != nil { log.Printf("launchctl failed: %v, output: %s", err, out); /* fix cause, retry once */ }

When it happens

Trigger: Running winfspLauncher "start" <service> <alias> <alias> <mountpoint> with cmd.Dir = WinFsp bin path, and the launcher process returns an error — service not registered, launcher cannot start the process, WinFsp driver issues, or invalid arguments.

Common situations: Service registry entry removed between registration and start (uninstall/cleanup tools); WinFsp driver not loaded (reboot pending after install); conflicting mount on the same drive letter; corrupted WinFsp installation.

Related errors

• Failed to update WinFsp service registry: %s
• failed to run command line: %s, %v
• Cannot mount to a local directory when --as-local-volume is
• Mount point %s cannot be an existing folder
• Parent directory %s of mount point %s does not exist

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