hashicorp/nomad · error

ErrCgroupMustBeSet

ErrCgroupMustBeSet

Error message

cgroup must be set

What it means

ErrCgroupMustBeSet is the Nomad executor's sentinel error indicating a cgroup path was required but empty. configureCgroups (stats collection) and setSubCmdCgroup (moving the exec subcommand into a cgroup) both wrap it when the resolved cgroup string is "", meaning the process is not under cgroup management where the executor expects it to be.

Source

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

	// ExecutorVersionPre0_9 is the version of executor use prior to the release
	// of 0.9.x
	ExecutorVersionPre0_9 = "1.1.0"

	// IsolationModePrivate represents the private isolation mode for a namespace
	IsolationModePrivate = "private"

	// IsolationModeHost represents the host isolation mode for a namespace
	IsolationModeHost = "host"
)

var (
	// The statistics the basic executor exposes
	ExecutorBasicMeasuredMemStats = []string{"RSS", "Swap"}
	ExecutorBasicMeasuredCpuStats = []string{"System Mode", "User Mode", "Percent"}

	// ErrCgroupMustBeSet occurs if a cgroup is not provided when expected
	ErrCgroupMustBeSet = errors.New("cgroup must be set")
)

// Executor is the interface which allows a driver to launch and supervise
// a process
type Executor interface {
	// Launch a user process configured by the given ExecCommand
	Launch(launchCmd *ExecCommand) (*ProcessState, error)

	// Wait blocks until the process exits or an error occures
	Wait(ctx context.Context) (*ProcessState, error)

	// Shutdown will shutdown the executor by stopping the user process,
	// cleaning up and resources created by the executor. The shutdown sequence
	// will first send the given signal to the process. This defaults to "SIGINT"
	// if not specified. The executor will then wait for the process to exit
	// before cleaning up other resources. If the executor waits longer than the
	// given grace period, the process is forcefully killed.
	//

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Ensure the Nomad client has cgroup v2 mounted and writable (stat -fc %T /sys/fs/cgroup should report cgroup2fs)
2. Run the client with sufficient privileges (root or CAP_SYS_ADMIN / CAP_DAC_OVERRIDE) so cgroups can be created
3. Check driver config for options disabling cgroup management and reconcile with the executor's expectations
4. Inspect client logs for an earlier cgroup setup failure that left the cgroup empty

// pre-flight client check
func cgroupsReady() error {
    if runtime.GOOS != "linux" { return errors.New("linux required") }
    if mt, err := statFSType("/sys/fs/cgroup"); err != nil || mt != "cgroup2fs" {
        return errors.New("cgroup v2 not mounted")
    }
    return nil
}

func hasCgroup(p string) bool { return p != "" }

if _, err := exec.Launch(cmd); err != nil {
    if errors.Is(err, executor.ErrCgroupMustBeSet) {
        return fmt.Errorf("client cgroup setup failed; check mounts/privileges: %w", err)
    }
    return err
}

When it happens

Trigger: configureCgroups when command.StatsCgroup() returns empty (e.g. cgroup setup was skipped, driver does not manage cgroups, or setup failed silently); setSubCmdCgroup when the computed subcommand cgroup is empty — commonly when the client runs without cgroup support or the task bypassed cgroup creation.

Common situations: Running Nomad on Linux without proper cgroup mounts/privileges; client configured with a driver/plugin that disables cgroup management while the executor still expects one; misconfigured cgroups_v2 override paths; container-in-container environments lacking write access to the cgroupfs.

Related errors

• unable to get orphaned task PIDs: %v
• unable to send signal to process %d: %v
• orphaned processes %v have not been removed from cgroups pid
• failed to set cpuset: %w
• only one of cgroups_v1_override and cgroups_v2_override may

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