🚨 Docker Error Guide: 'cgroups: cgroup mountpoint does not exist' — Align the cgroup Driver

Overview

This error appears when the container runtime tries to set up resource limits for a new container but cannot find the cgroup hierarchy it expects:

Error response from daemon: OCI runtime create failed: runc create failed: unable to apply cgroup configuration: cgroups: cgroup mountpoint does not exist: unknown

Containers use kernel cgroups to enforce CPU and memory limits. cgroup mountpoint does not exist means runc went looking for a cgroup mount at the path implied by Docker’s configured cgroup driver and found nothing there. On modern hosts this is almost always a driver mismatch: the host runs cgroup v2 with systemd managing the hierarchy, while Docker (or runc) is configured to use the cgroupfs driver that expects the older v1 layout. The two disagree about where cgroups live, so container creation fails.

Symptoms

• Every docker run fails at creation with unable to apply cgroup configuration: cgroups: cgroup mountpoint does not exist.
• The daemon starts fine, but no container will start — the failure is at container create, not daemon start.
• Common right after a distro upgrade that switched the host to cgroup v2 (unified hierarchy), or after copying a daemon.json between hosts with different cgroup setups.
• Kubernetes/kubelet on the same node may complain about a cgroup driver mismatch too.
• docker info shows a Cgroup Driver and Cgroup Version that do not match how the host is actually mounted.

Common Root Causes

• cgroup driver mismatch on cgroup v2 — host is unified/systemd-managed but Docker uses cgroupfs, so the expected mountpoint is absent.
• An explicit native.cgroupdriver=cgroupfs left in daemon.json on a host that has since moved to cgroup v2 + systemd.
• A configuration copied from a cgroup v1 host to a v2 host without adjusting the driver.
• Running inside a minimal container/VM where the cgroup filesystem is not mounted at all (unprivileged containers, some CI runners).
• systemd and Docker disagreeing about who owns the cgroup tree, so the hierarchy Docker targets never gets created.

Diagnostic Workflow

First determine the host’s cgroup version and what Docker thinks it is using — the two must agree:

docker info | grep -i 'cgroup'
mount | grep cgroup
stat -fc %T /sys/fs/cgroup/        # 'cgroup2fs' = v2 unified, 'tmpfs' = v1

If stat reports cgroup2fs (v2) but docker info shows Cgroup Driver: cgroupfs, that mismatch is the root cause. Read the daemon config and logs:

cat /etc/docker/daemon.json
journalctl -u docker --since '15 min ago' | grep -i 'cgroup\|runc\|oci runtime'

On systemd + cgroup v2 hosts, set Docker’s cgroup driver to systemd so it matches how the host manages the hierarchy. Edit /etc/docker/daemon.json:

{
  "exec-opts": ["native.cgroupdriver=systemd"]
}

Validate the JSON, then restart the daemon and confirm the driver flipped:

jq . /etc/docker/daemon.json
sudo systemctl restart docker
docker info | grep -i 'cgroup'

Finally verify a container can now create and apply cgroup limits:

docker run --rm --memory=256m alpine echo cgroups-ok

Example Root Cause Analysis

After an in-place OS upgrade, a build host that had happily run containers for months began failing every docker run with cgroups: cgroup mountpoint does not exist. The daemon started without error, but no container would.

stat -fc %T /sys/fs/cgroup/ returned cgroup2fs — the upgrade had switched the host to the cgroup v2 unified hierarchy, which systemd manages. But docker info | grep -i cgroup showed Cgroup Driver: cgroupfs, and cat /etc/docker/daemon.json revealed an explicit "exec-opts": ["native.cgroupdriver=cgroupfs"] set long ago on the old cgroup v1 system. On v2, the cgroupfs driver looks for a v1-style mountpoint that no longer exists, so runc failed at container create.

The fix was to align the driver with the host by switching to systemd:

{
  "exec-opts": ["native.cgroupdriver=systemd"]
}

After jq validation and sudo systemctl restart docker, docker info showed Cgroup Driver: systemd and Cgroup Version: 2, and docker run --rm --memory=256m alpine echo ok succeeded. The root cause was a stale cgroupfs driver setting carried across a v1-to-v2 upgrade — identified by the cgroup2fs/cgroupfs disagreement between stat and docker info.

Prevention Best Practices

• On systemd hosts with cgroup v2, standardize on native.cgroupdriver=systemd for Docker (and match kubelet’s cgroupDriver: systemd).
• Do not copy daemon.json verbatim between hosts without checking each host’s cgroup version with stat -fc %T /sys/fs/cgroup/.
• After OS upgrades, re-check docker info cgroup fields — upgrades commonly flip the host to cgroup v2.
• Keep Docker’s and any orchestrator’s cgroup driver identical on the same node; a split driver causes subtle limit-enforcement bugs even when containers start.
• Validate daemon.json with jq before restarting so a driver edit doesn’t turn into a daemon-won’t-start outage.

Quick Command Reference

# Host cgroup version vs. what Docker uses
stat -fc %T /sys/fs/cgroup/        # cgroup2fs = v2
docker info | grep -i cgroup
mount | grep cgroup

# Daemon config and errors
cat /etc/docker/daemon.json
journalctl -u docker --since '15 min ago' | grep -i cgroup

# Align the driver to systemd (cgroup v2 hosts)
# daemon.json: {"exec-opts": ["native.cgroupdriver=systemd"]}
jq . /etc/docker/daemon.json
sudo systemctl restart docker
docker info | grep -i cgroup

# Verify a container can apply limits
docker run --rm --memory=256m alpine echo cgroups-ok

Conclusion

cgroups: cgroup mountpoint does not exist is a container-create failure caused by Docker and the host disagreeing about the cgroup layout — classically a cgroupfs driver setting left over on a host that has moved to cgroup v2 with systemd. Diagnose it by comparing stat -fc %T /sys/fs/cgroup/ against docker info’s cgroup driver; when they disagree, set native.cgroupdriver=systemd in daemon.json, validate with jq, and restart. Keep the driver aligned across Docker and any orchestrator on the node, and re-check after OS upgrades that may flip the host to the unified hierarchy.