How to fix failed to create overlay filesystem: no space left on device in Docker

DockerINTERMEDIATEHIGHUpdated Dec 6, 2025· 337 views

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.

Quick fix

Fixes failed to create overlay filesystem: no space left on device

# 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/overlay2
  1. Check Docker disk usage and overlay2 size
  2. Prune unused Docker objects
  3. Clear the build cache
  4. Remove stopped containers and unused images individually
docker — error
# 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/overlay2
failed to create overlay filesystem: no space left on device

What this error means

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.

Typical symptoms

  • Container start fails with 'failed to create overlay filesystem' error
  • Docker run commands fail immediately after attempting to create the container
  • docker system df shows high disk usage, especially for images and build cache
  • /var/lib/docker/overlay2 directory consumes most of the disk space
  • New image pulls or builds fail with space-related errors
  • Other containers that were working suddenly cannot start

Common causes

  1. Accumulated unused Docker images and layers in /var/lib/docker/overlay2
  2. Build cache from repeated docker build commands consuming excessive space
  3. Stopped containers that haven't been removed still holding disk space
  4. Orphaned overlay2 layers from improperly removed images
  5. Containers writing large amounts of data to their writable layer
  6. The partition containing /var/lib/docker is too small for workload
  7. Inode exhaustion on the filesystem (many small files but no inodes left)

How to fix "failed to create overlay filesystem: no space left on device"

1Check Docker disk usage and overlay2 size

First, diagnose exactly how much space Docker and the overlay2 directory are using:

bash
# 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/overlay2

The overlay2 directory often contains the bulk of Docker's disk usage. If it's consuming most of your disk, proceed with cleanup.

2Prune unused Docker objects

Use Docker's built-in prune commands to safely remove unused resources:

bash
# 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 --volumes

The -a flag removes images not referenced by any container. After running this, you'll need to re-pull any images you need.

3Clear the build cache

Docker's build cache can grow very large with frequent builds. Clear it specifically:

bash
# Remove dangling build cache
docker builder prune

# Remove ALL build cache (recommended if space is critical)
docker builder prune -a

In some cases, build cache alone can consume tens of gigabytes. Clearing it often provides immediate relief.

4Remove stopped containers and unused images individually

For more targeted cleanup:

bash
# 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

5Identify containers writing excessive data

If a running container is filling up disk space, identify it:

bash
# 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 -20

If a container is writing large amounts of data, consider mounting a volume for that data instead of writing to the container's filesystem.

6Restart Docker daemon to release space

Sometimes Docker holds references to deleted files. Restart the daemon to release them:

bash
sudo systemctl restart docker

After restarting, check disk space again with df -h and docker system df.

7Verify space recovered and retry

Confirm the cleanup worked:

bash
# Check system disk space
df -h

# Check Docker's usage
docker system df

# Check overlay2 directory size
sudo du -sh /var/lib/docker/overlay2

Then retry your original Docker command. If you still have issues, see the advanced notes for additional options.

Advanced notes

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:

bash
# WARNING: This removes ALL Docker data including volumes
sudo systemctl stop docker
sudo rm -rf /var/lib/docker
sudo systemctl start docker

Moving Docker to a larger partition: If /var/lib/docker is on a small partition, move it:

bash
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 docker

Limiting log file size: Container logs can consume significant space. Add to /etc/docker/daemon.json:

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:

bash
# Add to cron or CI pipeline
docker system prune -f --filter "until=24h"
docker builder prune -f --filter "until=24h"

Frequently asked questions

What does "failed to create overlay filesystem: no space left on device" mean?
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.
How do I fix "failed to create overlay filesystem: no space left on device"?
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.
What causes "failed to create overlay filesystem: no space left on device"?
Accumulated unused Docker images and layers in /var/lib/docker/overlay2 Build cache from repeated docker build commands consuming excessive space Stopped containers that haven't been removed still holding disk space
Is the "failed to create overlay filesystem: no space left on device" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading