{"record":{"id":"07f6a478a4ec3149","repo":"juicedata/juicefs","slug":"fuse-is-not-installed-please-install-it-first","errorCode":null,"errorMessage":"fuse is not installed. Please install it first","messagePattern":"fuse is not installed\\. Please install it first","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/fuse/fuse.go","lineNumber":527,"sourceCode":"\t\t} else if strings.TrimSpace(n) != \"\" {\n\t\t\topt.Options = append(opt.Options, strings.TrimSpace(n))\n\t\t}\n\t}\n\tif !conf.NonDefaultPermission {\n\t\topt.Options = append(opt.Options, \"default_permissions\")\n\t}\n\tif runtime.GOOS == \"darwin\" {\n\t\topt.Options = append(opt.Options, \"fssubtype=juicefs\")\n\t\topt.Options = append(opt.Options, \"volname=\"+conf.Format.Name)\n\t\topt.Options = append(opt.Options, \"daemon_timeout=60\", \"iosize=65536\", \"novncache\")\n\t}\n\tfssrv, err := fuse.NewServer(imp, conf.Meta.MountPoint, &opt)\n\tif err != nil {\n\t\tif execErr, ok := err.(*exec.Error); ok {\n\t\t\tif pathErr, ok := execErr.Unwrap().(*os.PathError); ok &&\n\t\t\t\tstrings.Contains(pathErr.Path, \"fusermount\") &&\n\t\t\t\tpathErr.Unwrap() == syscall.ENOENT {\n\t\t\t\treturn fmt.Errorf(\"fuse is not installed. Please install it first\")\n\t\t\t}\n\t\t}\n\t\treturn fmt.Errorf(\"fuse: %s\", err)\n\t}\n\tdefer func() {\n\t\tif runtime.GOOS == \"darwin\" {\n\t\t\t_ = fssrv.Unmount()\n\t\t}\n\t}()\n\n\tif runtime.GOOS == \"linux\" {\n\t\tv.InvalidateEntry = func(parent Ino, name string) syscall.Errno {\n\t\t\treturn syscall.Errno(fssrv.EntryNotify(uint64(parent), name))\n\t\t}\n\t}\n\n\tfsserv = fssrv\n\tfssrv.Serve()","sourceCodeStart":509,"sourceCodeEnd":545,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/fuse/fuse.go#L509-L545","documentation":"During Serve, mounting via FUSE failed because executing fusermount produced an exec.Error wrapping an ENOENT PathError on a path containing 'fusermount'. JuiceFS interprets this as the FUSE userland tools not being installed and returns a friendly message asking to install FUSE first.","triggerScenarios":"Running `juicefs mount` (or mountMain) on Linux/macOS where the fusermount/fusermount3 binary is absent from PATH; minimal containers or chroots without the fuse package.","commonSituations":"Docker images without fuse packages (e.g. alpine/debian slim) attempting a FUSE mount; macOS without FUSE-T/macFUSE installed; PATH stripped in systemd services or cron so fusermount is not found.","solutions":["Install FUSE: Debian/Ubuntu `apt-get install -y fuse3` (or fuse), RHEL `yum install fuse3`, Alpine `apk add fuse3`, macOS install FUSE-T or macFUSE.","Ensure fusermount(3) is in PATH for the user running JuiceFS (`which fusermount3 fusermount`).","In containers, mount with `--privileged` or `--device /dev/fuse --cap-add SYS_ADMIN` and install the fuse package.","If FUSE is present but PATH-limited, fix PATH in the service unit/environment."],"exampleFix":"// Dockerfile before\nFROM debian:slim\nRUN apt-get install -y ca-certificates\n\n// after\nFROM debian:slim\nRUN apt-get update && apt-get install -y ca-certificates fuse3","handlingStrategy":"fallback","validationCode":"// check before mounting\nif _, err := exec.LookPath(\"fusermount3\"); err != nil {\n    if _, err := exec.LookPath(\"fusermount\"); err != nil {\n        return errors.New(\"install fuse (fusermount) before mounting\")\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := jfs.Mount(mp, meta, opts); err != nil {\n    if strings.Contains(err.Error(), \"fuse is not installed\") {\n        return installFuseHint() // actionable message to user\n    }\n    return err\n}","preventionTips":["Bake fuse3/fuse into container images used for mounting","Verify `which fusermount3` in entrypoint scripts","On macOS install FUSE-T/macFUSE before first mount","Don't strip PATH in systemd units/cron that run juicefs mount"],"tags":["fuse","mount","missing-dependency","fusermount"],"backgroundTag":"missing-optional-dependency","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}