Debian 12 – Docker overlay2 No Space Left on Device – Host Cleanup Playbook

📖 ~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 fail writes or crash because overlay2 storage reaches filesystem capacity.

Environment & Reproduction

Seen on busy CI and app hosts where image and log retention lacks lifecycle controls.

Root Cause Analysis

Unused layers, build cache, and oversized container logs consume disk faster than cleanup jobs.

Quick Triage

Run docker system df and identify highest-growth images, volumes, and log directories.

Step-by-Step Diagnosis

Correlate container churn patterns with overlay2 directory growth and host partition saturation.

Solution – Primary Fix

Prune safely, rotate container logs, and move Docker root to larger storage if needed.

Solution – Alternative Approaches

Adopt immutable image policy with registry retention to reduce local build cache pressure.

Verification & Acceptance Criteria

Sufficient free space returns and container restarts and writes succeed under normal load.

Rollback Plan

Restore required images from registry if aggressive pruning removes active dependencies.

Prevention & Hardening

Automate cleanup windows and enforce disk quotas and log rotation for container hosts.

Related Errors & Cross-Refs

write: no space left on device and overlay2 mount operation failures.

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 storage driver docs and Debian host operations recommendations.