juicedata/juicefs · error

fuse: %s

Error message

fuse: %s

What it means

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.

Source

Thrown at pkg/fuse/fuse.go:530

	}
	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()
	return nil
}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. 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`).
2. In containers, run with --device /dev/fuse and CAP_SYS_ADMIN (or use the rootless/mount-compatible setup).
3. Check mountpoint permissions and that it is an empty existing directory.
4. On macOS, install FUSE-T or macFUSE before mounting.

Example fix

# before (container)
docker run juicefs mount redis://... /mnt/jfs

# after
docker run --device /dev/fuse --cap-add SYS_ADMIN juicefs mount redis://... /mnt/jfs

// preflight: mountpoint exists, is a dir, and fuse is available
if fi, err := os.Stat(mp); err != nil || !fi.IsDir() { os.MkdirAll(mp, 0755) }
exec.LookPath("fusermount3")
_, err := os.Stat("/dev/fuse")

if err := jfs.Mount(mp, meta, opts); err != nil {
    if strings.Contains(err.Error(), "fuse:") {
        // inspect wrapped cause: stale mount? /dev/fuse missing? perms?
        exec.Command("fusermount", "-u", mp).Run() // clear stale entry, then retry
    }
    return err
}

When it happens

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

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

Related errors

• fuse is not installed. Please install it first
• invalid cgroup entry: %q
• write message: %s
• clone failed: %v
• open control file for [%d:%s]: %w

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