Debian 9 – Docker or containerd fails after cgroup v2 migration

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Container runtime startup fails and orchestrated workloads stop launching.

Environment & Reproduction

Occurs after kernel boot parameter or runtime configuration changes affecting cgroups.

# Capture baseline
docker info 2>/dev/null | sed -n 1,80p || true
containerd --version 2>/dev/null || true
cat /proc/cgroups
mount | grep cgroup

Root Cause Analysis

Runtime and kernel cgroup mode expectations are mismatched, causing initialization failure.

Quick Triage

Identify active cgroup hierarchy and runtime driver settings.

# Quick triage
stat -fc %T /sys/fs/cgroup
grep cgroup /proc/filesystems
systemctl status docker containerd --no-pager

Step-by-Step Diagnosis

Inspect runtime logs for cgroup controller and driver compatibility errors.

# Detailed diagnosis
journalctl -u docker -u containerd -n 200 --no-pager
cat /etc/docker/daemon.json 2>/dev/null
cat /etc/containerd/config.toml 2>/dev/null | sed -n 1,120p

Solution – Primary Fix

Align runtime cgroup driver and kernel mode, then restart runtime services.

# Primary fix
sudo mkdir -p /etc/docker
printf {n  "exec-opts": ["native.cgroupdriver=systemd"]n}n | sudo tee /etc/docker/daemon.json
sudo systemctl restart containerd docker

Solution – Alternative Approaches

Pin runtime to known-good version and boot mode until migration plan is complete.

# Alternatives
sudo apt-cache policy docker.io containerd
sudo update-grub
sudo reboot

Verification & Acceptance Criteria

Runtime starts cleanly and test containers run successfully.

# Verify
systemctl is-active docker
docker run --rm hello-world 2>/dev/null || true

Rollback Plan

Revert runtime config and kernel parameters to prior known-good state.

# Rollback
sudo rm -f /etc/docker/daemon.json
sudo systemctl restart docker containerd

Prevention & Hardening

Test cgroup changes in staging and lock runtime configuration drift.

# Hardening
docker info 2>/dev/null | grep -Ei cgroup
systemctl status docker --no-pager

Related Errors & Cross-Refs

Related to OCI runtime create failed and cgroup mountpoint not found.

Related tutorial: View the step-by-step tutorial for Debian 9.

View all Debian 9 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Docker, containerd, and Linux cgroup compatibility documentation.