{"record":{"id":"b048482c2659a068","repo":"k3s-io/k3s","slug":"pids-cgroup-controller-not-found","errorCode":null,"errorMessage":"pids cgroup controller not found","messagePattern":"pids cgroup controller not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/daemons/agent/agent_linux.go","lineNumber":131,"sourceCode":"\t// If the embedded CCM is disabled, don't assume that dual-stack node IPs are safe.\n\t// When using an external CCM, the user wants dual-stack node IPs, they will need to set the node-ip kubelet arg directly.\n\t// This should be fine since most cloud providers have their own way of finding node IPs that doesn't depend on the kubelet\n\t// setting them.\n\tif cfg.DisableCCM {\n\t\tdualStack, err := utilsnet.IsDualStackIPs(cfg.NodeIPs)\n\t\tif err == nil && !dualStack {\n\t\t\targsMap[\"node-ip\"] = cfg.NodeIP\n\t\t}\n\t} else {\n\t\targsMap[\"cloud-provider\"] = \"external\"\n\t\tif nodeIPs := util.JoinIPs(cfg.NodeIPs); nodeIPs != \"\" {\n\t\t\targsMap[\"node-ip\"] = util.JoinIPs(cfg.NodeIPs)\n\t\t}\n\t}\n\n\tkubeletRoot, runtimeRoot, controllers := cgroups.CheckCgroups()\n\tif !controllers[\"pids\"] {\n\t\treturn nil, nil, errors.New(\"pids cgroup controller not found\")\n\t}\n\tif !controllers[\"cpu\"] {\n\t\tlogrus.Warn(\"Disabling CPU quotas due to missing cpu controller or cpu.cfs_period_us\")\n\t\tdefaultConfig.CPUCFSQuota = utilsptr.To(false)\n\t}\n\tif kubeletRoot != \"\" {\n\t\tdefaultConfig.KubeletCgroups = kubeletRoot\n\t}\n\tif runtimeRoot != \"\" {\n\t\targsMap[\"runtime-cgroups\"] = runtimeRoot\n\t}\n\n\targsMap[\"node-labels\"] = strings.Join(cfg.NodeLabels, \",\")\n\n\tif ImageCredProvAvailable(cfg) {\n\t\tlogrus.Infof(\"Kubelet image credential provider bin dir and configuration file found.\")\n\t\targsMap[\"image-credential-provider-bin-dir\"] = cfg.ImageCredProvBinDir\n\t\targsMap[\"image-credential-provider-config\"] = cfg.ImageCredProvConfig","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/daemons/agent/agent_linux.go#L113-L149","documentation":"Before building kubelet args, cgroups.CheckCgs() scans /sys/fs/cgroup for available controllers; the 'pids' controller is mandatory (kubelet requires it for pod limits), so its absence is fatal. The 'cpu' controller absence is only a warning (CPU quotas disabled), contrasted inline.","triggerScenarios":"Host has cgroup v1 without the pids controller; k3s runs inside a container whose /sys/fs/cgroup view hides pids; kernel booted with cgroup_no_pids or a minimal controller set; some WSL2/older-LTS kernels.","commonSituations":"Running k3s in Docker without --cgroupns=host / privileged; minimal VMs or NAS kernels lacking pids; cgroup v1 hybrid systems predating pids support.","solutions":["On the host verify: grep pids /sys/fs/cgroup/cgroup.controllers (v2) or existence of /sys/fs/cgroup/pids (v1).","Run k3s directly on the host or in a properly privileged container (host cgroup namespace: --cgroupns=host, full /sys mount).","Enable the pids controller in systemd slices (ensure no cgroup hierarchy excludes pids) and prefer cgroup v2 unified mode.","For WSL2/old kernels, upgrade to a kernel with pids controller support."],"exampleFix":"# before: pids hidden inside container\ndocker run ... k3s server\n# after: expose host cgroups\ndocker run --privileged --cgroupns=host -v /sys/fs/cgroup:/sys/fs/cgroup ... k3s server","handlingStrategy":"validation","validationCode":"// Same probe CheckCgroups performs, as a pre-flight:\ndata, _ := os.ReadFile(\"/sys/fs/cgroup/cgroup.controllers\") // cgroup v2\nif !strings.Contains(string(data), \"- pids\") && !strings.Contains(string(data), \"pids\") {\n\tif _, err := os.Stat(\"/sys/fs/cgroup/pids\"); err != nil { // cgroup v1 fallback\n\t\treturn errors.New(\"pids controller unavailable: kubelet cannot run; fix host cgroups\")\n\t}\n}","typeGuard":null,"tryCatchPattern":"if _, _, err := agent.KubeletArgs(cfg); err != nil {\n\tif strings.Contains(err.Error(), \"pids cgroup controller not found\") {\n\t\t// host-level fix: privileged container / cgroupns=host / enable pids; not retryable in-place\n\t}\n}","preventionTips":["Run k3s directly on hosts or in privileged containers with the host cgroup namespace.","Include a pids-controller check in node bootstrap/pre-flight for clusters on VMs.","Standardize on cgroup v2 unified mode; it makes pids delegation and detection deterministic."],"tags":["k3s","cgroups","kubelet","linux","container"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}