juicedata/juicefs · error

fail to find device cgroup

Error message

fail to find device cgroup

What it means

After scanning /proc/self/cgroup, grantAccess requires a line whose controller field is exactly 'devices' (cgroup v1). If no such line was found, the device cgroup path is empty and the function fails — it cannot locate the cgroup directory that controls device access.

Source

Thrown at pkg/fuse/device_linux.go:70

	for cgroupScanner.Scan() {
		if err := cgroupScanner.Err(); err != nil {
			return errors.Wrap(err, "read cgroup file")
		}
		var (
			text  = cgroupScanner.Text()
			parts = strings.SplitN(text, ":", 3)
		)
		if len(parts) < 3 {
			return errors.Errorf("invalid cgroup entry: %q", text)
		}

		if parts[1] == "devices" {
			deviceCgroup = parts[2]
		}
	}

	if len(deviceCgroup) == 0 {
		return errors.Errorf("fail to find device cgroup")
	}

	deviceListPath := path.Join("/sys/fs/cgroup/devices" + deviceCgroup, "/devices.list")
	deviceAllowPath := path.Join("/sys/fs/cgroup/devices" + deviceCgroup, "/devices.allow")

	// check if fuse is already allowed
	deviceListFile, err := os.OpenFile(deviceListPath, os.O_RDONLY, 0)
	if err != nil {
		return errors.Wrapf(err, "open %s", deviceListPath)
	}
	defer deviceListFile.Close()
	deviceListScanner := bufio.NewScanner(deviceListFile)
	for deviceListScanner.Scan() {
		if err := deviceListScanner.Err(); err != nil {
			return errors.Wrap(err, "read device list file")
		}
		var (
			text  = deviceListScanner.Text()

View on GitHub (pinned to c9a67b23e8)

Solutions

  1. Verify /proc/self/cgroup contains a 'N:devices:/path' line; if not, the system uses cgroup v2
  2. Boot with systemd.unified_cgroup_hierarchy=0 or configure the container runtime to use cgroup v1 for this container
  3. Grant /dev/fuse access outside JuiceFS: echo 'c 10:229 rwm' > /sys/fs/cgroup/devices/.../devices.allow as root on the host, or pass --device /dev/fuse to Docker
  4. Mount with sufficient privileges (run as root with SYS_ADMIN) or pre-grant the device

Example fix

// before (cgroup v2 host, docker default)
docker run juicefs mount ...
// fail to find device cgroup
// after
docker run --device /dev/fuse --cap-add SYS_ADMIN juicefs mount ...
Defensive patterns

Strategy: validation

Validate before calling

if data, err := os.ReadFile("/proc/self/cgroup"); err == nil && !strings.Contains(string(data), ":devices:") {
  // devices controller absent (cgroup v2 or restricted container): grant device out-of-band
}

Type guard

func devicesControllerPresent() bool {
  out, err := os.ReadFile("/proc/self/cgroup")
  return err == nil && strings.Contains(string(out), ":devices:")
}

Try / catch

if err := grantAccess(); err != nil && strings.Contains(err.Error(), "fail to find device cgroup") {
  return fmt.Errorf("cgroup v2 detected or devices controller unavailable; grant /dev/fuse manually: %w", err)
}

Prevention

When it happens

Trigger: Running on a cgroup v2 (unified hierarchy) system where /proc/self/cgroup has no 'devices' controller entry, or in a container where the devices controller is not exposed to the process.

Common situations: Modern Linux distros (Debian 11+, Ubuntu 21.10+, Fedora 31+) defaulting to cgroup v2; Kubernetes nodes with cgroup v2; Docker containers without the devices cgroup mounted.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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