Ubuntu 26.04 LTS – Docker daemon fails after cgroup configuration mismatch – Fix & Prevention

📖 ~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

Docker service does not start, preventing containerized applications from running.

Environment & Reproduction

Often seen after daemon.json edits, runtime upgrades, or kernel parameter changes.

systemctl status docker
docker info 2>/dev/null || true
cat /etc/docker/daemon.json 2>/dev/null

Root Cause Analysis

Mismatched cgroup driver configuration between Docker and host init system causes startup failure.

Quick Triage

Read recent daemon logs and effective cgroup mode.

journalctl -u docker -n 120 --no-pager
stat -fc %T /sys/fs/cgroup
ps -p 1 -o comm=

Step-by-Step Diagnosis

Validate JSON syntax and identify conflicting runtime settings.

sudo python3 -m json.tool /etc/docker/daemon.json >/dev/null
grep -RIn 'native.cgroupdriver|cgroup' /etc/docker/daemon.json /etc/default/grub 2>/dev/null

Solution – Primary Fix

Set a compatible cgroup driver and restart Docker cleanly.

sudo tee /etc/docker/daemon.json >/dev/null <<'EOF'
{
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file"
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

Solution – Alternative Approaches

Use distro-default Docker packages if custom runtime settings are not required.

sudo apt install -y --reinstall docker.io
sudo systemctl restart docker

Verification & Acceptance Criteria

Docker daemon stays active and can run test containers.

systemctl is-active docker
docker info
docker run --rm hello-world

Rollback Plan

Restore previous daemon.json and restart service if new config breaks workloads.

sudo cp /etc/docker/daemon.json.bak /etc/docker/daemon.json 2>/dev/null || true
sudo systemctl restart docker

Prevention & Hardening

Version-control daemon.json and validate configuration before rollout.

sudo python3 -m json.tool /etc/docker/daemon.json
systemctl status docker --no-pager

Related Errors & Cross-Refs

Related to containerd version skew, overlay filesystem issues, and exhausted inode space.

Related tutorial: View the step-by-step tutorial for Ubuntu 26.04 LTS.

View all Ubuntu 26.04 LTS tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Ubuntu Docker package documentation and cgroup integration guidance.