{"record":{"id":"799981d576b287a2","repo":"hashicorp/nomad","slug":"errcgroupmustbeset","errorCode":"ErrCgroupMustBeSet","errorMessage":"cgroup must be set","messagePattern":"cgroup must be set","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/shared/executor/executor.go","lineNumber":55,"sourceCode":"\n\t// ExecutorVersionPre0_9 is the version of executor use prior to the release\n\t// of 0.9.x\n\tExecutorVersionPre0_9 = \"1.1.0\"\n\n\t// IsolationModePrivate represents the private isolation mode for a namespace\n\tIsolationModePrivate = \"private\"\n\n\t// IsolationModeHost represents the host isolation mode for a namespace\n\tIsolationModeHost = \"host\"\n)\n\nvar (\n\t// The statistics the basic executor exposes\n\tExecutorBasicMeasuredMemStats = []string{\"RSS\", \"Swap\"}\n\tExecutorBasicMeasuredCpuStats = []string{\"System Mode\", \"User Mode\", \"Percent\"}\n\n\t// ErrCgroupMustBeSet occurs if a cgroup is not provided when expected\n\tErrCgroupMustBeSet = errors.New(\"cgroup must be set\")\n)\n\n// Executor is the interface which allows a driver to launch and supervise\n// a process\ntype Executor interface {\n\t// Launch a user process configured by the given ExecCommand\n\tLaunch(launchCmd *ExecCommand) (*ProcessState, error)\n\n\t// Wait blocks until the process exits or an error occures\n\tWait(ctx context.Context) (*ProcessState, error)\n\n\t// Shutdown will shutdown the executor by stopping the user process,\n\t// cleaning up and resources created by the executor. The shutdown sequence\n\t// will first send the given signal to the process. This defaults to \"SIGINT\"\n\t// if not specified. The executor will then wait for the process to exit\n\t// before cleaning up other resources. If the executor waits longer than the\n\t// given grace period, the process is forcefully killed.\n\t//","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/shared/executor/executor.go#L37-L73","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the Nomad client has cgroup v2 mounted and writable (stat -fc %T /sys/fs/cgroup should report cgroup2fs)","Run the client with sufficient privileges (root or CAP_SYS_ADMIN / CAP_DAC_OVERRIDE) so cgroups can be created","Check driver config for options disabling cgroup management and reconcile with the executor's expectations","Inspect client logs for an earlier cgroup setup failure that left the cgroup empty"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// pre-flight client check\nfunc cgroupsReady() error {\n    if runtime.GOOS != \"linux\" { return errors.New(\"linux required\") }\n    if mt, err := statFSType(\"/sys/fs/cgroup\"); err != nil || mt != \"cgroup2fs\" {\n        return errors.New(\"cgroup v2 not mounted\")\n    }\n    return nil\n}","typeGuard":"func hasCgroup(p string) bool { return p != \"\" }","tryCatchPattern":"if _, err := exec.Launch(cmd); err != nil {\n    if errors.Is(err, executor.ErrCgroupMustBeSet) {\n        return fmt.Errorf(\"client cgroup setup failed; check mounts/privileges: %w\", err)\n    }\n    return err\n}","preventionTips":["Run nomad clients with privileges to create cgroups (root or CAP_SYS_ADMIN)","Verify cgroup v2 is mounted at /sys/fs/cgroup on every client","Watch client logs for earlier cgroup setup warnings before launch failures","Avoid driver configs that skip cgroup management while relying on executor stats"],"tags":["cgroups","linux","executor","nomad"],"backgroundTag":"cgroup-not-configured","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}