{"record":{"id":"1d405aa10f2f4c9e","repo":"k3s-io/k3s","slug":"unhandled-cgroup-mode","errorCode":null,"errorMessage":"unhandled cgroup mode","messagePattern":"unhandled cgroup mode","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/cgroups/cgroups_linux.go","lineNumber":27,"sourceCode":"\t\"os\"\n\t\"path/filepath\"\n\t\"strings\"\n\n\tcgroups \"github.com/containerd/cgroups/v3\"\n\tcgroupsv1 \"github.com/containerd/cgroups/v3/cgroup1\"\n\tcgroupsv2 \"github.com/containerd/cgroups/v3/cgroup2\"\n\t\"github.com/k3s-io/k3s/pkg/version\"\n\t\"github.com/sirupsen/logrus\"\n)\n\nfunc Validate() error {\n\tswitch cgroups.Mode() {\n\tcase cgroups.Unified:\n\t\treturn validateCgroupsV2()\n\tcase cgroups.Legacy, cgroups.Hybrid:\n\t\treturn validateCgroupsV1()\n\tdefault:\n\t\treturn errors.New(\"unhandled cgroup mode\")\n\t}\n}\n\nfunc validateCgroupsV1() error {\n\tcontrollers, err := cgroupsv1.Default()\n\tif err != nil {\n\t\treturn err\n\t}\n\tm := make(map[string]struct{})\n\tfor _, controller := range controllers {\n\t\tname := string(controller.Name())\n\t\tm[name] = struct{}{}\n\t}\n\n\tif _, ok := m[\"cpuset\"]; !ok {\n\t\tlogrus.Warn(`Failed to find cpuset cgroup, you may need to add \"cgroup_enable=cpuset\" to your linux cmdline (/boot/cmdline.txt on a Raspberry Pi)`)\n\t}\n","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/cgroups/cgroups_linux.go#L9-L45","documentation":"At startup k3s validates the host cgroup layout using containerd's cgroups.Mode(): Unified (v2 only), Legacy (v1 only), or Hybrid (v1 + v2 mounted). Any other value — practically the Unavailable mode returned when the cgroup filesystem cannot be detected — falls through to this error. It aborts startup because kubelet/cadvisor cannot manage resources without a known cgroup hierarchy.","triggerScenarios":"Running k3s in an environment where /sys/fs/cgroup is missing, not mounted, or unreadable: minimal VMs/initramfs, misconfigured containers running k3s-in-docker with cgroup namespaces hiding the hierarchy, or unusual runtimes.","commonSituations":"k3s inside a Docker/Podman container started without a proper cgroup mount; stripped cloud images/WSL2 setups where cgroup detection fails; nested virtualization with restricted /sys exposure.","solutions":["On bare metal/VMs, ensure the host boots with a standard cgroup setup (cgroup v2 unified or legacy v1) so /sys/fs/cgroup is mounted","For k3s-in-container, run the container with host cgroup visibility (e.g. privileged with cgroup mounts) or use k3d/docker's --privileged with proper volume mounts","Check `stat -fc %T /sys/fs/cgroup` (expect cgroup2fs or tmpfs) and mount the cgroup filesystem if absent"],"exampleFix":"# before\nmount | grep cgroup # empty -> unhandled cgroup mode\n\n# after (inside a container host namespace)\nmount -t cgroup2 none /sys/fs/cgroup\nsystemctl restart k3s","handlingStrategy":"validation","validationCode":"func cgroupModeSupported() error {\n    switch cgroups.Mode() {\n    case cgroups.Unified, cgroups.Legacy, cgroups.Hybrid:\n        return nil\n    default:\n        return fmt.Errorf(\"cgroup mode unavailable (Mode=%d); mount /sys/fs/cgroup properly before starting k3s\", cgroups.Mode())\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Preflight hosts with `stat -fc %T /sys/fs/cgroup` expecting cgroup2fs/tmpfs","For k3s-in-container, use documented privileged/mount setups (k3d) rather than plain docker run","Add infrastructure checks to node bootstrap (bare-metal, VM, container) before installing k3s"],"tags":["cgroups","linux","startup","container","host"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}