Debian 12 – Docker daemon fails to start after updates – 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

Containers are unavailable because dockerd exits on startup.

Environment & Reproduction

Common after cgroup driver mismatch, storage driver issues, or daemon.json errors.

cat /etc/os-release
systemctl status docker --no-pager
docker info

Root Cause Analysis

Docker runtime config conflicts with kernel/cgroup state or invalid JSON syntax.

Quick Triage

Inspect daemon logs and validate config file.

sudo journalctl -u docker -n 200 --no-pager
sudo dockerd --validate --config-file /etc/docker/daemon.json

Step-by-Step Diagnosis

Check cgroup mode, storage driver compatibility, and disk availability.

stat -fc %T /sys/fs/cgroup
df -h /var/lib/docker
cat /etc/docker/daemon.json

Solution – Primary Fix

Correct daemon config and align cgroup driver with systemd.

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

Solution – Alternative Approaches

Temporarily move corrupted Docker data directory and reinitialize engine.

sudo systemctl stop docker
sudo mv /var/lib/docker /var/lib/docker.bak
sudo systemctl start docker

Verification & Acceptance Criteria

Docker service stays active and test container runs successfully.

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

Rollback Plan

Restore prior daemon.json and data directory if regression occurs.

sudo cp /root/daemon.json.bak /etc/docker/daemon.json
sudo systemctl restart docker

Prevention & Hardening

Version-lock critical runtime components and test upgrades in staging.

apt-cache policy docker-ce
sudo apt-mark hold docker-ce docker-ce-cli

Related Errors & Cross-Refs

Related errors include failed to start daemon and cgroup driver mismatch.

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

View all Debian 12 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Docker on Debian installation and cgroup compatibility docs.