{"record":{"id":"908805434272741f","repo":"juicedata/juicefs","slug":"fuse-s","errorCode":null,"errorMessage":"fuse: %s","messagePattern":"fuse: %s","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/fuse/fuse.go","lineNumber":530,"sourceCode":"\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()\n\treturn nil\n}\n","sourceCodeStart":512,"sourceCodeEnd":548,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/fuse/fuse.go#L512-L548","documentation":"Generic wrapper for any FUSE NewServer failure that is not the specific 'fusermount missing' case: Serve returns `fuse: %s` with the underlying error. This covers mountpoint problems, permission issues, /dev/fuse unavailability, and other libfuse/bazil-fuse errors.","triggerScenarios":"Calling `juicefs mount` when the mountpoint does not exist, is already in use, /dev/fuse is missing or not accessible (container without devices/caps), fusermount exists but fails (permissions, stale mount), or the OS lacks FUSE support.","commonSituations":"Mounting inside unprivileged Docker/Kubernetes without --device /dev/fuse --cap-add SYS_ADMIN; mountpoint already mounted (stale entry needing fusermount -u); macOS without macFUSE/FUSE-T; kernel module fuse not loaded (modprobe fuse).","solutions":["Read the wrapped error: fix the specific cause (create the mountpoint, unmount stale entry with `fusermount -u`, load the fuse kernel module with `modprobe fuse`).","In containers, run with --device /dev/fuse and CAP_SYS_ADMIN (or use the rootless/mount-compatible setup).","Check mountpoint permissions and that it is an empty existing directory.","On macOS, install FUSE-T or macFUSE before mounting."],"exampleFix":"# before (container)\ndocker run juicefs mount redis://... /mnt/jfs\n\n# after\ndocker run --device /dev/fuse --cap-add SYS_ADMIN juicefs mount redis://... /mnt/jfs","handlingStrategy":"try-catch","validationCode":"// preflight: mountpoint exists, is a dir, and fuse is available\nif fi, err := os.Stat(mp); err != nil || !fi.IsDir() { os.MkdirAll(mp, 0755) }\nexec.LookPath(\"fusermount3\")\n_, err := os.Stat(\"/dev/fuse\")","typeGuard":null,"tryCatchPattern":"if err := jfs.Mount(mp, meta, opts); err != nil {\n    if strings.Contains(err.Error(), \"fuse:\") {\n        // inspect wrapped cause: stale mount? /dev/fuse missing? perms?\n        exec.Command(\"fusermount\", \"-u\", mp).Run() // clear stale entry, then retry\n    }\n    return err\n}","preventionTips":["Ensure /dev/fuse is present and CAP_SYS_ADMIN granted in containers","Create the mountpoint directory before mounting","Unload stale mounts with `fusermount -u` before remounting","Load the fuse kernel module (`modprobe fuse`) on minimal kernels"],"tags":["fuse","mount","fuse-server"],"backgroundTag":"mount-failed","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"}