juicedata/juicefs · error

fuse is not installed. Please install it first

Error message

fuse is not installed. Please install it first

What it means

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.

Source

Thrown at pkg/fuse/fuse.go:527

		} else if strings.TrimSpace(n) != "" {
			opt.Options = append(opt.Options, strings.TrimSpace(n))
		}
	}
	if !conf.NonDefaultPermission {
		opt.Options = append(opt.Options, "default_permissions")
	}
	if runtime.GOOS == "darwin" {
		opt.Options = append(opt.Options, "fssubtype=juicefs")
		opt.Options = append(opt.Options, "volname="+conf.Format.Name)
		opt.Options = append(opt.Options, "daemon_timeout=60", "iosize=65536", "novncache")
	}
	fssrv, err := fuse.NewServer(imp, conf.Meta.MountPoint, &opt)
	if err != nil {
		if execErr, ok := err.(*exec.Error); ok {
			if pathErr, ok := execErr.Unwrap().(*os.PathError); ok &&
				strings.Contains(pathErr.Path, "fusermount") &&
				pathErr.Unwrap() == syscall.ENOENT {
				return fmt.Errorf("fuse is not installed. Please install it first")
			}
		}
		return fmt.Errorf("fuse: %s", err)
	}
	defer func() {
		if runtime.GOOS == "darwin" {
			_ = fssrv.Unmount()
		}
	}()

	if runtime.GOOS == "linux" {
		v.InvalidateEntry = func(parent Ino, name string) syscall.Errno {
			return syscall.Errno(fssrv.EntryNotify(uint64(parent), name))
		}
	}

	fsserv = fssrv
	fssrv.Serve()

View on GitHub (pinned to c9a67b23e8)

Solutions

  1. 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.
  2. Ensure fusermount(3) is in PATH for the user running JuiceFS (`which fusermount3 fusermount`).
  3. In containers, mount with `--privileged` or `--device /dev/fuse --cap-add SYS_ADMIN` and install the fuse package.
  4. If FUSE is present but PATH-limited, fix PATH in the service unit/environment.

Example fix

// Dockerfile before
FROM debian:slim
RUN apt-get install -y ca-certificates

// after
FROM debian:slim
RUN apt-get update && apt-get install -y ca-certificates fuse3
Defensive patterns

Strategy: fallback

Validate before calling

// check before mounting
if _, err := exec.LookPath("fusermount3"); err != nil {
    if _, err := exec.LookPath("fusermount"); err != nil {
        return errors.New("install fuse (fusermount) before mounting")
    }
}

Try / catch

if err := jfs.Mount(mp, meta, opts); err != nil {
    if strings.Contains(err.Error(), "fuse is not installed") {
        return installFuseHint() // actionable message to user
    }
    return err
}

Prevention

When it happens

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

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

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

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