This error occurs when Docker's overlay2 storage driver cannot create the filesystem layers needed for containers due to insufficient disk space in /var/lib/docker. The fix involves cleaning up Docker resources and reclaiming space in the overlay2 directory.
The "failed to create overlay filesystem: no space left on device" error is specific to Docker's overlay2 storage driver, which is the default storage driver on most modern Linux systems. This error indicates that Docker cannot create the layered filesystem required to run a container because there's no space left on the partition where Docker stores its data. The overlay2 driver stores image and container layers in the /var/lib/docker/overlay2 directory. Each Docker image is composed of multiple layers, and when you run a container, overlay2 creates a union mount combining these read-only layers with a writable layer on top. When the disk fills up, this mount operation fails. Unlike generic "no space left on device" errors, this specific error points directly to a problem with the overlay filesystem creation, which typically means the /var/lib/docker/overlay2 directory has grown too large. This commonly happens because Docker doesn't automatically clean up unused layers, stopped containers, or build cache, leading to gradual disk space exhaustion.
First, diagnose exactly how much space Docker and the overlay2 directory are using:
# Check Docker's built-in disk usage report
docker system df
# Show detailed breakdown
docker system df -v
# Check overall disk usage
df -h
# Check overlay2 directory size specifically
sudo du -sh /var/lib/docker/overlay2The overlay2 directory often contains the bulk of Docker's disk usage. If it's consuming most of your disk, proceed with cleanup.
Use Docker's built-in prune commands to safely remove unused resources:
# Remove stopped containers, unused networks, dangling images, and build cache
docker system prune
# For more aggressive cleanup, remove ALL unused images (not just dangling)
docker system prune -a
# Include volumes in the cleanup (WARNING: removes unused volume data)
docker system prune -a --volumesThe -a flag removes images not referenced by any container. After running this, you'll need to re-pull any images you need.
Docker's build cache can grow very large with frequent builds. Clear it specifically:
# Remove dangling build cache
docker builder prune
# Remove ALL build cache (recommended if space is critical)
docker builder prune -aIn some cases, build cache alone can consume tens of gigabytes. Clearing it often provides immediate relief.
For more targeted cleanup:
# List all containers including stopped ones
docker ps -a
# Remove all stopped containers
docker container prune -f
# List all images
docker images -a
# Remove dangling images (layers not referenced by any image)
docker image prune -f
# Remove all unused images
docker image prune -a -f
# Remove specific images by ID
docker rmi <image_id>Check for large images with docker images --format "{{.Size}}\t{{.Repository}}:{{.Tag}}" | sort -h
If a running container is filling up disk space, identify it:
# Show container disk usage
docker ps -s
# Find which files a container has changed
docker container diff <container_id>
# Check size of each overlay2 layer's writable directory
sudo du -sh /var/lib/docker/overlay2/*/diff | sort -h | tail -20If a container is writing large amounts of data, consider mounting a volume for that data instead of writing to the container's filesystem.
Sometimes Docker holds references to deleted files. Restart the daemon to release them:
sudo systemctl restart dockerAfter restarting, check disk space again with df -h and docker system df.
Confirm the cleanup worked:
# Check system disk space
df -h
# Check Docker's usage
docker system df
# Check overlay2 directory size
sudo du -sh /var/lib/docker/overlay2Then retry your original Docker command. If you still have issues, see the advanced notes for additional options.
Understanding overlay2 internals: The overlay2 directory contains subdirectories for each layer. Each has:
- diff/: The actual filesystem content of that layer
- link: A shortened identifier for the layer
- lower: References to underlying layers (for non-base layers)
- merged/: The unified view when mounted (only for running containers)
- work/: Working directory for overlay filesystem operations
When prune doesn't reclaim enough space: Docker prune only removes objects Docker knows about. Orphaned layers can remain if Docker crashed during image removal. As a last resort:
# WARNING: This removes ALL Docker data including volumes
sudo systemctl stop docker
sudo rm -rf /var/lib/docker
sudo systemctl start dockerMoving Docker to a larger partition: If /var/lib/docker is on a small partition, move it:
sudo systemctl stop docker
sudo mv /var/lib/docker /new/path/docker
# Edit /etc/docker/daemon.json:
# { "data-root": "/new/path/docker" }
sudo systemctl start dockerLimiting log file size: Container logs can consume significant space. Add to /etc/docker/daemon.json:
{
"log-driver": "json-file",
"log-opts": {
"max-size": "10m",
"max-file": "3"
}
}Inode exhaustion: If df -ih shows 100% inode usage but disk space available, the issue is too many files (Docker layers create many small files). The only fix is cleaning up Docker objects or reformatting with more inodes.
Docker Desktop (Mac/Windows): The overlay2 directory exists inside Docker's virtual machine. Adjust disk size in Docker Desktop Settings > Resources > Advanced. On Mac, you can reset Docker Desktop to reclaim space (loses all data).
Prevention: Set up automated cleanup in CI/CD:
# Add to cron or CI pipeline
docker system prune -f --filter "until=24h"
docker builder prune -f --filter "until=24h"unable to configure the Docker daemon with file /etc/docker/daemon.json
How to fix 'unable to configure the Docker daemon with file daemon.json' in Docker
docker: Error response from daemon: OCI runtime create failed: container_linux.go: starting container process caused: exec: "/docker-entrypoint.sh": stat /docker-entrypoint.sh: no such file or directory
How to fix 'exec: entrypoint.sh: no such file or directory' in Docker
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker