How to fix cgroups: cgroup mountpoint does not exist: unknown in Docker

DockerADVANCEDHIGHUpdated Dec 1, 2025· 315 views

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.

Quick fix

Fixes cgroups: cgroup mountpoint does not exist: unknown

# 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 cgroup
  1. Check your cgroup version
  2. Check your Docker version
  3. Update Docker to version 20.10 or later
  4. Fall back to cgroup v1 (if upgrade not possible)
docker — error
# 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 cgroup
cgroups: cgroup mountpoint does not exist: unknown

What this error means

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.

Typical symptoms

  • Docker containers fail to start with 'cgroup mountpoint does not exist: unknown'
  • docker run or docker-compose up fails immediately
  • Error appears in GitLab CI/CD runners using Kubernetes executor with docker-in-docker
  • Docker daemon starts but containers cannot be created
  • Error mentions 'OCI runtime create failed' with cgroup-related messages
  • The /sys/fs/cgroup directory is empty or missing expected subdirectories
  • Docker worked on previous OS version but fails after upgrade

Common causes

  1. System uses cgroup v2 (unified hierarchy) but Docker version only supports cgroup v1
  2. Running Docker inside a container without proper cgroup mounts (docker-in-docker)
  3. Kernel boot parameters don't include cgroup configuration
  4. The /sys/fs/cgroup filesystem is not mounted
  5. Virtualization platform (OpenVZ, Virtuozzo) doesn't expose cgroups properly
  6. WSL1 or older Windows Subsystem for Linux without cgroup support
  7. Outdated Docker version (< 20.10) on modern Linux distribution
  8. Missing systemd cgroup mount when using systemd-based systems

How to fix "cgroups: cgroup mountpoint does not exist: unknown"

1Check your cgroup version

First, determine which cgroup version your system is using:

bash
# 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 cgroup

If you see "cgroup2" in the mount output or the cgroup.controllers file exists, your system uses cgroup v2.

2Check your Docker version

Verify your Docker version supports cgroup v2:

bash
docker version

Cgroup 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:

bash
# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh

# Or use package manager with Docker's official repo
3Update Docker to version 20.10 or later

If running an older Docker version, upgrade to get cgroup v2 support:

bash
# 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 version
4Fall back to cgroup v1 (if upgrade not possible)

If you cannot upgrade Docker, you can configure your system to use cgroup v1:

bash
# 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 reboot

For Fedora/RHEL systems:

bash
sudo dnf install grubby
sudo grubby --update-kernel=ALL --args="systemd.unified_cgroup_hierarchy=0"
sudo reboot

Warning: This is a workaround, not a long-term solution. Cgroup v2 is the future, and reverting to v1 may cause issues with other software.

5Manually mount cgroups (for containers/VMs)

If running Docker inside a container or minimal VM where cgroups aren't mounted:

bash
# 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
done

For Docker Machine / Docker Toolbox:

bash
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"
6Configure Docker daemon for cgroup v2

For Docker 20.10+ with cgroup v2, you may need to configure the cgroup driver:

bash
# 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 docker

The native.cgroupdriver=systemd option is recommended for systems using systemd. The default-cgroupns-mode setting can help with cgroup namespace issues.

7Fix Docker-in-Docker (GitLab CI/Kubernetes)

For GitLab CI runners using Kubernetes executor with docker-in-docker:

Update the Docker image version in .gitlab-ci.yml:

yaml
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:

yaml
volumes:
  - name: cgroup
    hostPath:
      path: /sys/fs/cgroup
      type: Directory
volumeMounts:
  - name: cgroup
    mountPath: /sys/fs/cgroup
    readOnly: true

Note: If using CRI-O as the container runtime, Docker 19.03 has known compatibility issues. Upgrade to Docker 20.10+.

8Enable cgroup memory controller (if needed)

Some errors related to cgroup mountpoints involve missing memory controller support:

bash
# 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 reboot

After reboot, verify memory cgroup is enabled:

bash
cat /proc/cgroups | grep memory
# Should show: memory  X  X  1 (where 1 means enabled)
9Verify the fix

After applying the appropriate fix, verify Docker works correctly:

bash
# 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_bytes

The test container should start successfully and report the memory limit.

Advanced notes

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:

bash
# Check kubelet cgroup driver
cat /var/lib/kubelet/config.yaml | grep cgroupDriver

Mismatch between Docker and kubelet cgroup drivers causes instability.

Rootless Docker and Cgroups:
Rootless Docker requires cgroup v2 with delegation enabled:

bash
# Enable cgroup delegation for user
sudo mkdir -p /etc/systemd/system/user@.service.d
sudo tee /etc/systemd/system/user@.service.d/delegate.conf <<EOF
[Service]
Delegate=cpu cpuset io memory pids
EOF
sudo systemctl daemon-reload

OpenVZ/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:

bash
# List all cgroup mounts
findmnt -t cgroup,cgroup2

# Check specific controller availability
cat /proc/cgroups

WSL2 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:

powershell
wsl --set-version <distro-name> 2

Frequently asked questions

What does "cgroups: cgroup mountpoint does not exist: unknown" mean?
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. 10+, Debian 11+) that defaults to cgroup v2.
How do I fix "cgroups: cgroup mountpoint does not exist: unknown"?
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.
What causes "cgroups: cgroup mountpoint does not exist: unknown"?
System uses cgroup v2 (unified hierarchy) but Docker version only supports cgroup v1 Running Docker inside a container without proper cgroup mounts (docker-in-docker) Kernel boot parameters don't include cgroup configuration
Is the "cgroups: cgroup mountpoint does not exist: unknown" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading