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

Container workloads stop because dockerd fails during startup.

Environment & Reproduction

Often appears after kernel, cgroup, or storage-driver changes.

sudo systemctl status docker
docker info
sudo journalctl -u docker -n 120 --no-pager

Root Cause Analysis

Incompatible cgroup mode, corrupted metadata, or invalid daemon.json settings.

Quick Triage

Check daemon logs and current cgroup/storage settings.

cat /etc/docker/daemon.json 2>/dev/null
stat -fc %T /sys/fs/cgroup
lsblk -f

Step-by-Step Diagnosis

Validate config syntax and inspect runtime dependencies.

sudo dockerd --validate --config-file /etc/docker/daemon.json 2>/dev/null || true
containerd --version
journalctl -u containerd -n 80 --no-pager

Solution – Primary Fix

Correct daemon config and restart container runtime stack.

sudo cp -a /etc/docker/daemon.json /var/tmp/daemon.json.bak.$(date +%s) 2>/dev/null || true
sudoedit /etc/docker/daemon.json
sudo systemctl restart containerd
sudo systemctl restart docker

Solution – Alternative Approaches

Reset Docker state directory only after workload backup.

sudo systemctl stop docker
sudo mv /var/lib/docker /var/lib/docker.bak.$(date +%s)
sudo systemctl start docker

Verification & Acceptance Criteria

Docker daemon becomes active and test container runs.

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

Rollback Plan

Restore previous daemon config and data directory if regression occurs.

sudo systemctl stop docker
sudo cp -a /var/tmp/daemon.json.bak.* /etc/docker/daemon.json 2>/dev/null || true
sudo systemctl start docker

Prevention & Hardening

Pin tested Docker versions and validate config changes pre-deploy.

apt-cache policy docker-ce docker.io
sudo dockerd --validate --config-file /etc/docker/daemon.json 2>/dev/null || true

Related Errors & Cross-Refs

Can coincide with overlay filesystem corruption and full-disk incidents.

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

View all Debian 11 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Debian and Docker engine operational documentation.