hashicorp/nomad · error

unable to configure cgroups: %w

Error message

unable to configure cgroups: %w

What it means

Launch calls configureResourceContainer to place the task under a cgroup for isolation. If that fails AND the executor runs as root or uses a custom cgroup parent, the failure is fatal and wrapped with this message. Non-root executors log a warning and continue, since cgroups are expected to be unavailable there.

Source

Thrown at drivers/shared/executor/executor.go:390

	// set the task dir as the working directory for the command
	if e.command.WorkDir != "" {
		e.childCmd.Dir = e.command.WorkDir
	} else {
		e.childCmd.Dir = e.command.TaskDir
	}

	// start command in separate process group
	if err := e.setNewProcessGroup(); err != nil {
		return nil, err
	}

	// setup containment (i.e. cgroups on linux)
	running, cleanup, err := e.configureResourceContainer(command, os.Getpid())
	if err != nil {
		e.logger.Error("failed to configure container, process isolation will not work", "error", err)
		if os.Geteuid() == 0 || e.usesCustomCgroup() {
			return nil, fmt.Errorf("unable to configure cgroups: %w", err)
		}
		// keep going if we are not root; some folks run nomad as non-root and
		// expect this driver to still work
	} else {
		defer cleanup()
	}

	stdout, err := e.command.Stdout()
	if err != nil {
		return nil, err
	}
	stderr, err := e.command.Stderr()
	if err != nil {
		return nil, err
	}

	e.childCmd.Stdout = stdout
	e.childCmd.Stderr = stderr

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check the wrapped %w cause to identify the cgroup subsystem failure
2. Ensure /sys/fs/cgroup is mounted and writable by the nomad client (not read-only)
3. Verify kernel cmdline hasn't disabled required controllers (cgroup_disable=...)
4. Upgrade Nomad for cgroup v2 support or boot with systemd.unified_cgroup_hierarchy=0 as a workaround
5. If running nomad as non-root intentionally, confirm Geteuid()!=0 so execution continues with a warning

Example fix

// before
// mount: ro /sys/fs/cgroup in container running nomad
// after (docker run)
// docker run --cgroupns=host -v /sys/fs/cgroup:/sys/fs/cgroup:rw ...

func cgroupsUsable() error {
  st, err := os.Stat("/sys/fs/cgroup")
  if err != nil { return err }
  if !st.IsDir() { return errors.New("/sys/fs/cgroup not a dir") }
  test := "/sys/fs/cgroup/.nomad-probe"
  if err := os.Mkdir(test, 0o755); err != nil { return fmt.Errorf("cgroup not writable: %w", err) }
  os.Remove(test)
  return nil
}

if err := launchTask(); err != nil {
  if strings.Contains(err.Error(), "unable to configure cgroups") {
    log.Printf("cgroup isolation unavailable: %v — continuing without resource limits", err)
    return launchWithoutCgroups() // or fail fast if isolation is mandatory
  }
  return err
}

When it happens

Trigger: configureResourceContainer returns an error — e.g. cgroup v2 hierarchy unexpected, /sys/fs/cgroup not writable, cgroup subsystem unavailable, systemd cgroup driver mismatch, or existing cgroup path conflicts.

Common situations: Nomad client running as root on a host with cgroup v2 and an older Nomad, cgroup controllers disabled via kernel cmdline (cgroup_disable=memory), containers-in-containers (nested cgroup limits), read-only /sys/fs/cgroup mount, invalid client cgroup config.

Related errors

• ErrCgroupMustBeSet
• failed to create nomad cgroup %s: %w
• failed to set cpuset.mems on nomad cpuset cgroup: %w
• failed to write cores to nomad cpuset cgroup: %w
• failed to create share cpuset partition: %w

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/5d8f714c3d3e3b8b. Report an issue: GitHub.