{"record":{"id":"a5737b9c93f32d76","repo":"juicedata/juicefs","slug":"fail-to-find-device-cgroup","errorCode":null,"errorMessage":"fail to find device cgroup","messagePattern":"fail to find device cgroup","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/fuse/device_linux.go","lineNumber":70,"sourceCode":"\tfor cgroupScanner.Scan() {\n\t\tif err := cgroupScanner.Err(); err != nil {\n\t\t\treturn errors.Wrap(err, \"read cgroup file\")\n\t\t}\n\t\tvar (\n\t\t\ttext  = cgroupScanner.Text()\n\t\t\tparts = strings.SplitN(text, \":\", 3)\n\t\t)\n\t\tif len(parts) < 3 {\n\t\t\treturn errors.Errorf(\"invalid cgroup entry: %q\", text)\n\t\t}\n\n\t\tif parts[1] == \"devices\" {\n\t\t\tdeviceCgroup = parts[2]\n\t\t}\n\t}\n\n\tif len(deviceCgroup) == 0 {\n\t\treturn errors.Errorf(\"fail to find device cgroup\")\n\t}\n\n\tdeviceListPath := path.Join(\"/sys/fs/cgroup/devices\" + deviceCgroup, \"/devices.list\")\n\tdeviceAllowPath := path.Join(\"/sys/fs/cgroup/devices\" + deviceCgroup, \"/devices.allow\")\n\n\t// check if fuse is already allowed\n\tdeviceListFile, err := os.OpenFile(deviceListPath, os.O_RDONLY, 0)\n\tif err != nil {\n\t\treturn errors.Wrapf(err, \"open %s\", deviceListPath)\n\t}\n\tdefer deviceListFile.Close()\n\tdeviceListScanner := bufio.NewScanner(deviceListFile)\n\tfor deviceListScanner.Scan() {\n\t\tif err := deviceListScanner.Err(); err != nil {\n\t\t\treturn errors.Wrap(err, \"read device list file\")\n\t\t}\n\t\tvar (\n\t\t\ttext  = deviceListScanner.Text()","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/fuse/device_linux.go#L52-L88","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify /proc/self/cgroup contains a 'N:devices:/path' line; if not, the system uses cgroup v2","Boot with systemd.unified_cgroup_hierarchy=0 or configure the container runtime to use cgroup v1 for this container","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","Mount with sufficient privileges (run as root with SYS_ADMIN) or pre-grant the device"],"exampleFix":"// before (cgroup v2 host, docker default)\ndocker run juicefs mount ...\n// fail to find device cgroup\n// after\ndocker run --device /dev/fuse --cap-add SYS_ADMIN juicefs mount ...","handlingStrategy":"validation","validationCode":"if data, err := os.ReadFile(\"/proc/self/cgroup\"); err == nil && !strings.Contains(string(data), \":devices:\") {\n  // devices controller absent (cgroup v2 or restricted container): grant device out-of-band\n}","typeGuard":"func devicesControllerPresent() bool {\n  out, err := os.ReadFile(\"/proc/self/cgroup\")\n  return err == nil && strings.Contains(string(out), \":devices:\")\n}","tryCatchPattern":"if err := grantAccess(); err != nil && strings.Contains(err.Error(), \"fail to find device cgroup\") {\n  return fmt.Errorf(\"cgroup v2 detected or devices controller unavailable; grant /dev/fuse manually: %w\", err)\n}","preventionTips":["Detect cgroup v2 hosts early (stat -fc %T /sys/fs/cgroup) and use BPF-based device grants","Add --device /dev/fuse and capabilities to container specs so grantAccess is unnecessary","Document cgroup v1 requirement for deployments relying on automatic device grants"],"tags":["linux","cgroups","fuse","cgroup-v2"],"backgroundTag":"resource-not-found","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"}