{"record":{"id":"ebc14352a0dd8359","repo":"hashicorp/nomad","slug":"failed-to-set-subtree-control-on-nomad-cgroup-w","errorCode":null,"errorMessage":"failed to set subtree control on nomad cgroup: %w","messagePattern":"failed to set subtree control on nomad cgroup: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/lib/cgroupslib/init.go","lineNumber":154,"sourceCode":"\t\t// clients with delegated cgroups typically won't be able to write to\n\t\t// the subtree file, but that's ok so long as the required controllers\n\t\t// are activated\n\t\tif !functionalCgroups2(subtreeFile) {\n\t\t\tif err := writeCG(activation, subtreeFile); err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to create nomad cgroup: %w\", err)\n\t\t\t}\n\t\t}\n\n\t\t//\n\t\t// configuring nomad.slice\n\t\t//\n\n\t\tif err := mkCG(NomadCgroupParent); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create nomad cgroup: %w\", err)\n\t\t}\n\n\t\tif err := writeCG(activation, NomadCgroupParent, subtreeFile); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to set subtree control on nomad cgroup: %w\", err)\n\t\t}\n\n\t\tif err := writeCG(cores, NomadCgroupParent, cpusetFile); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to write root partition cpuset: %w\", err)\n\t\t}\n\n\t\tlog.Debug(\"top level partition root nomad.slice cgroup initialized\")\n\n\t\t//\n\t\t// configuring nomad.slice/share (member)\n\t\t//\n\n\t\tif err := mkCG(NomadCgroupParent, SharePartition()); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create share cgroup: %w\", err)\n\t\t}\n\n\t\tif err := writeCG(activation, NomadCgroupParent, SharePartition(), subtreeFile); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to set subtree control on cpuset share partition: %w\", err)","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/lib/cgroupslib/init.go#L136-L172","documentation":"During cgroups v2 client initialization, Nomad creates its top-level nomad.slice cgroup and writes the controller activation list (+cpuset +memory, etc.) to its cgroup.subtree_control file. This error wraps any failure writing that file, meaning Nomad cannot enable controllers for child cgroups and task isolation will not work.","triggerScenarios":"Init() is called on a cgroups v2 host and os.WriteFile on /sys/fs/cgroup/nomad.slice/cgroup.subtree_control fails — typically EACCES (process lacks write access to the root cgroup), EBUSY (a controller already enabled in a child blocks activation), or the nomad.slice directory was created but is read-only.","commonSituations":"Nomad agent run as non-root or in a container without cgroup write privileges; systemd owns the root cgroup and delegates only a subtree to Nomad (delegated cgroups); cgroup filesystem mounted read-only; controllers not available in /sys/fs/cgroup/cgroup.controllers so activation fails.","solutions":["Run the Nomad agent as root (or with CAP_SYS_ADMIN / appropriate cgroup delegation) so it can write to /sys/fs/cgroup/nomad.slice/cgroup.subtree_control.","Check that the needed controllers are listed in /sys/fs/cgroup/cgroup.controllers and not already enabled in child cgroups (EBUSY); disable conflicting children or reboot.","Verify /sys/fs/cgroup is mounted rw (mount | grep cgroup); remount without 'ro' if needed.","If using systemd cgroup delegation, delegate the subtree to the Nomad service (Delegate=yes) and configure Nomad to use the delegated path."],"exampleFix":"// before\nsudo nomad agent -config /etc/nomad.d\n// after (systemd unit with cgroup delegation)\n[Service]\nExecStart=/usr/bin/nomad agent -config /etc/nomad.d\nDelegate=yes\nCapabilityBoundingSet=CAP_SYS_ADMIN","handlingStrategy":"validation","validationCode":"func canWriteSubtreeControl() error {\n  b, err := os.ReadFile(\"/sys/fs/cgroup/cgroup.controllers\")\n  if err != nil { return err }\n  if len(b) == 0 { return errors.New(\"no controllers available at root cgroup\") }\n  return syscall.Access(\"/sys/fs/cgroup/nomad.slice\", syscall.W_OK)\n}","typeGuard":"func cgroupWritable(path string) bool {\n  return syscall.Access(filepath.Join(path, \"cgroup.subtree_control\"), syscall.W_OK) == nil\n}","tryCatchPattern":"if err := cgroupslib.Init(logger, cores); err != nil {\n  var perr *fs.PathError\n  if errors.As(err, &perr) && errors.Is(perr.Err, syscall.EACCES) {\n    logger.Error(\"run nomad as root or delegate cgroups (systemd Delegate=yes)\", \"path\", perr.Path)\n  }\n  return err\n}","preventionTips":["Run the Nomad agent as root or via systemd with Delegate=yes + appropriate CapabilityBoundingSet.","Check /sys/fs/cgroup/cgroup.controllers before start to confirm needed controllers exist.","Verify the cgroup mount is rw (mount | grep cgroup).","On EBUSY, ensure no processes live under nomad.slice before starting the agent."],"tags":["linux","cgroups","cgroupv2","filesystem-permissions"],"backgroundTag":"cgroup-write-permission-denied","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}