Debian 9 – 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

Common on CI and app hosts without image, layer, and log retention controls.

Root Cause Analysis

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

Quick Triage

Run docker system df and locate highest-growth images, volumes, and logs.

Step-by-Step Diagnosis

Correlate container churn with overlay2 growth and host partition saturation.

Solution – Primary Fix

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

Solution – Alternative Approaches

Adopt immutable images and registry retention policies to reduce local cache pressure.

Verification & Acceptance Criteria

Free space returns and container write operations succeed under normal load.

Rollback Plan

Restore required images from registry if aggressive pruning removes dependencies.

Prevention & Hardening

Automate cleanup windows and enforce disk quotas with container log rotation.

Related Errors & Cross-Refs

No space left on device and overlay2 mount or write failures.

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 storage driver documentation and Debian container host guidance.