{"record":{"id":"2190bdb2c458552f","repo":"juicedata/juicefs","slug":"failed-to-mount-juicefs-as-system-service-s-out","errorCode":null,"errorMessage":"Failed to mount juicefs as system service: %s, output: %s","messagePattern":"Failed to mount juicefs as system service: (.+?), output: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/winfsp/winfs.go","lineNumber":1468,"sourceCode":"\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))\n\t\t}\n\n\t\tif !checkIfMountProcessReady(mountpoint, 25) {\n\t\t\treturn 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)\n\t\t}\n\t} else {\n\t\tlogger.Debugf(\"Trying to start juicefs service by 'net use' command.\")\n\t\tcmd := exec.Command(\"net\", \"use\", mountpoint, fmt.Sprintf(\"\\\\\\\\%s\\\\%s\", winfspServiceName, alias), \"/Y\")\n\t\tout, err := cmd.CombinedOutput()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to start juicefs service by 'net use': %s, output: %s\", err, string(out))\n\t\t}\n\t}\n\n\tlogger.Info(\"Juicefs mount process started successfully.\")\n\n\treturn nil\n}","sourceCodeStart":1450,"sourceCodeEnd":1486,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/winfsp/winfs.go#L1450-L1486","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the 'output:' portion of the message — it contains launchctl's actual failure reason.","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).","Reboot after a fresh WinFsp install so the WinFsp driver is loaded, then retry.","Free the target drive letter/mountpoint if another process holds it, and retry."],"exampleFix":"// before\nlaunchctl-x64.exe start juicefs-myjfs ... // exit 1: service not found\n// after: re-run mount to re-register, then verify\n> juicefs mount redis://... X:\n> launchctl-x64.exe list","handlingStrategy":"retry","validationCode":"// ensure service is registered and launcher binary exists before starting\nif _, err := os.Stat(filepath.Join(winFspBinPath, \"launchctl-x64.exe\")); err != nil { return err }\nif _, 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\") }","typeGuard":null,"tryCatchPattern":"out, err := cmd.CombinedOutput()\nif err != nil { log.Printf(\"launchctl failed: %v, output: %s\", err, out); /* fix cause, retry once */ }","preventionTips":["Read the launcher output embedded in the error before retrying","Reboot after WinFsp install so the driver is loaded","Remove stale service registrations before re-mounting","Free the drive letter/mountpoint before starting"],"tags":["windows","winfsp","service","process"],"backgroundTag":"command-not-found","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"}