This error occurs when Docker cannot find the expected cgroup filesystem mount, typically due to incompatibility between Docker and cgroup v2 (unified cgroup hierarchy). Modern Linux distributions have migrated to cgroup v2, which older Docker versions may not fully support.
Control groups (cgroups) are a Linux kernel feature that Docker uses to limit and isolate resource usage (CPU, memory, disk I/O) for containers. The cgroup filesystem must be mounted at /sys/fs/cgroup for Docker to function. This error appears when: - The cgroup filesystem is not mounted at all (common in minimal containers or VMs) - Docker expects cgroup v1 but the system uses cgroup v2 (unified hierarchy) - Running Docker inside a container or VM that doesn't expose the host's cgroup mounts - The systemd cgroup controller hasn't properly mounted cgroups - Kernel boot parameters are missing cgroup configuration The most common scenario is running an older Docker version (19.03 or earlier) on a modern Linux distribution (Fedora 31+, Ubuntu 21.10+, Debian 11+) that defaults to cgroup v2. Docker versions prior to 20.10 have limited or no support for cgroup v2.
First, determine which cgroup version your system is using:
# Check if cgroup v2 is in use
if [ -f /sys/fs/cgroup/cgroup.controllers ]; then
echo "cgroup v2 (unified hierarchy) is active"
else
echo "cgroup v1 (legacy hierarchy) is active"
fi
# Alternative: check mount type
mount | grep cgroupIf you see "cgroup2" in the mount output or the cgroup.controllers file exists, your system uses cgroup v2.
Verify your Docker version supports cgroup v2:
docker versionCgroup v2 support timeline:
- Docker 20.10+: Full cgroup v2 support
- Docker 19.03: Limited/experimental cgroup v2 support
- Docker < 19.03: No cgroup v2 support
If you're running Docker < 20.10, upgrade to a newer version:
# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
# Or use package manager with Docker's official repoIf running an older Docker version, upgrade to get cgroup v2 support:
# Remove old Docker packages
sudo apt-get remove docker docker-engine docker.io containerd runc
# Install prerequisites
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
# Add the repository
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Verify installation
docker versionIf you cannot upgrade Docker, you can configure your system to use cgroup v1:
# Edit GRUB configuration
sudo nano /etc/default/grub
# Add to GRUB_CMDLINE_LINUX:
GRUB_CMDLINE_LINUX="systemd.unified_cgroup_hierarchy=0"
# Update GRUB
sudo update-grub
# Reboot
sudo rebootFor Fedora/RHEL systems:
sudo dnf install grubby
sudo grubby --update-kernel=ALL --args="systemd.unified_cgroup_hierarchy=0"
sudo rebootWarning: This is a workaround, not a long-term solution. Cgroup v2 is the future, and reverting to v1 may cause issues with other software.
If running Docker inside a container or minimal VM where cgroups aren't mounted:
# Mount the cgroup filesystem
sudo mkdir -p /sys/fs/cgroup
sudo mount -t tmpfs cgroup_root /sys/fs/cgroup
# Mount systemd cgroup (often required)
sudo mkdir -p /sys/fs/cgroup/systemd
sudo mount -t cgroup -o none,name=systemd cgroup /sys/fs/cgroup/systemd
# For cgroup v1, mount individual controllers
for controller in cpu cpuacct cpuset memory devices freezer net_cls blkio; do
sudo mkdir -p /sys/fs/cgroup/$controller
sudo mount -t cgroup -o $controller cgroup /sys/fs/cgroup/$controller
doneFor Docker Machine / Docker Toolbox:
docker-machine ssh default "sudo mkdir -p /sys/fs/cgroup/systemd"
docker-machine ssh default "sudo mount -t cgroup -o none,name=systemd cgroup /sys/fs/cgroup/systemd"For Docker 20.10+ with cgroup v2, you may need to configure the cgroup driver:
# Create or edit daemon.json
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
"exec-opts": ["native.cgroupdriver=systemd"],
"default-cgroupns-mode": "host"
}
EOF
# Restart Docker
sudo systemctl restart dockerThe native.cgroupdriver=systemd option is recommended for systems using systemd. The default-cgroupns-mode setting can help with cgroup namespace issues.
For GitLab CI runners using Kubernetes executor with docker-in-docker:
Update the Docker image version in .gitlab-ci.yml:
services:
- docker:20.10.16-dind # Use 20.10+ instead of 19.03
variables:
DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_CERTDIR: "/certs"For Kubernetes pod configuration, ensure proper volume mounts:
volumes:
- name: cgroup
hostPath:
path: /sys/fs/cgroup
type: Directory
volumeMounts:
- name: cgroup
mountPath: /sys/fs/cgroup
readOnly: trueNote: If using CRI-O as the container runtime, Docker 19.03 has known compatibility issues. Upgrade to Docker 20.10+.
Some errors related to cgroup mountpoints involve missing memory controller support:
# Check if memory cgroup is enabled
cat /proc/cgroups | grep memory
# If disabled, edit GRUB configuration
sudo nano /etc/default/grub
# Add memory controller options:
GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1"
# Update GRUB and reboot
sudo update-grub
sudo rebootAfter reboot, verify memory cgroup is enabled:
cat /proc/cgroups | grep memory
# Should show: memory X X 1 (where 1 means enabled)After applying the appropriate fix, verify Docker works correctly:
# Check Docker daemon status
sudo systemctl status docker
# Verify cgroup driver configuration
docker info | grep -i cgroup
# Run a test container
docker run --rm hello-world
# Check container resource constraints work
docker run --rm --memory=100m alpine cat /sys/fs/cgroup/memory.max 2>/dev/null || \
docker run --rm --memory=100m alpine cat /sys/fs/cgroup/memory/memory.limit_in_bytesThe test container should start successfully and report the memory limit.
Cgroup v1 vs v2 Differences:
- Cgroup v1 (legacy): Multiple hierarchies, each controller mounted separately (/sys/fs/cgroup/cpu, /sys/fs/cgroup/memory, etc.)
- Cgroup v2 (unified): Single hierarchy, all controllers in one tree (/sys/fs/cgroup with cgroup.controllers file)
Distribution Timeline for Cgroup v2 Default:
- Fedora 31+ (October 2019): First major distro to default to cgroup v2
- Ubuntu 21.10+ (October 2021): Switched to cgroup v2
- Debian 11 (August 2021): Supports both, defaults depend on configuration
- RHEL 9 / CentOS Stream 9: Cgroup v2 by default
- Arch Linux: Cgroup v2 for several years
Kubernetes Considerations:
When running Kubernetes, ensure all components (kubelet, container runtime) are configured consistently:
# Check kubelet cgroup driver
cat /var/lib/kubelet/config.yaml | grep cgroupDriverMismatch between Docker and kubelet cgroup drivers causes instability.
Rootless Docker and Cgroups:
Rootless Docker requires cgroup v2 with delegation enabled:
# Enable cgroup delegation for user
sudo mkdir -p /etc/systemd/system/[email protected]
sudo tee /etc/systemd/system/[email protected]/delegate.conf <<EOF
[Service]
Delegate=cpu cpuset io memory pids
EOF
sudo systemctl daemon-reloadOpenVZ/Virtuozzo Containers:
Docker in OpenVZ containers is problematic because OpenVZ has its own resource management layer. You may need:
- VZ kernel 3.10.0-1127 or newer
- Container configuration with cgroup mounts enabled
- Privileged container mode
Checking Cgroup Mounts:
# List all cgroup mounts
findmnt -t cgroup,cgroup2
# Check specific controller availability
cat /proc/cgroupsWSL2 vs WSL1:
WSL1 does not support cgroups. WSL2 runs a real Linux kernel and supports Docker natively. If you're on Windows, ensure you're using WSL2:
wsl --set-version <distro-name> 2unable to configure the Docker daemon with file /etc/docker/daemon.json
How to fix 'unable to configure the Docker daemon with file daemon.json' in Docker
docker: Error response from daemon: OCI runtime create failed: container_linux.go: starting container process caused: exec: "/docker-entrypoint.sh": stat /docker-entrypoint.sh: no such file or directory
How to fix 'exec: entrypoint.sh: no such file or directory' in Docker
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker