How to fix devmapper: Thin Pool has free data blocks which is less than minimum required in Docker

DockerINTERMEDIATEHIGHUpdated Dec 6, 2025· 175 views

This error occurs when Docker's devicemapper thin pool runs out of free data blocks. The fix involves cleaning up unused Docker resources, extending the thin pool, or migrating to the overlay2 storage driver.

Quick fix

Fixes devmapper: Thin Pool has free data blocks which is less than minimum required

docker info | grep -A 20 "Storage Driver"
  1. Check thin pool disk usage
  2. Clean up Docker resources
  3. Save and reload images (if pruning doesn't help)
  4. Extend the LVM thin pool
docker — error
docker info | grep -A 20 "Storage Driver"
devmapper: Thin Pool has free data blocks which is less than minimum required

What this error means

The "Thin Pool has free data blocks which is less than minimum required" error occurs when using Docker with the devicemapper storage driver. Docker maintains a minimum free space threshold in the thin pool to ensure safe operation. When free data blocks fall below this threshold, Docker prevents new operations to avoid data corruption. The devicemapper driver uses Linux's device mapper thin provisioning (dm-thinp) module to implement copy-on-write snapshots for container storage. Each time you pull an image or create a container, Docker creates thin devices within the pool. Over time, these accumulate and consume the available space. This error is particularly common on RHEL/CentOS systems and older Docker installations where devicemapper was the default storage driver. The error can block container creation, image pulls, and other Docker operations until space is freed or the pool is expanded.

Typical symptoms

  • Docker run fails with 'Thin Pool has X free data blocks which is less than minimum required Y'
  • Docker pull operations fail unexpectedly
  • Container creation fails even when system disk shows available space
  • 'docker info' shows high Data Space Used percentage
  • CI/CD pipelines fail at container start or image pull steps
  • AWS Elastic Beanstalk or ECS deployments fail with thin pool errors

Common causes

  1. Accumulated unused images and containers filling the thin pool
  2. Thin pool size configured too small for workload
  3. Autoextend disabled or not configured for the thin pool
  4. Large images consuming significant thin pool space
  5. Docker not properly cleaning up layers from deleted images
  6. Using loopback mode instead of direct-lvm (loopback has fixed size limits)
  7. Minimum free space threshold (dm.min_free_space) set too high

How to fix "devmapper: Thin Pool has free data blocks which is less than minimum required"

1Check thin pool disk usage

First, examine the current state of your thin pool:

bash
docker info | grep -A 20 "Storage Driver"

Look for these key values:
- Data Space Used / Data Space Total: How much of the thin pool is consumed
- Thin Pool Minimum Free Space: The threshold that triggers this error

Also check LVM thin pool status directly:

bash
sudo lvs

This shows the data percentage used for each logical volume.

2Clean up Docker resources

Remove unused containers, images, and volumes to free space:

bash
# Remove stopped containers
docker container prune -f

# Remove unused images
docker image prune -a -f

# Remove unused volumes
docker volume prune -f

# Or clean everything at once
docker system prune -a --volumes -f

Note: On some systems with devicemapper issues, pruning may not immediately recover thin pool space. You may need to restart Docker after pruning:

bash
sudo systemctl restart docker
3Save and reload images (if pruning doesn't help)

If pruning doesn't recover space due to orphaned layers, try saving active images and reloading them:

bash
# Save important images to tar files
docker save -o myapp.tar myapp:latest

# Remove all images
docker rmi $(docker images -q) -f

# Reload the images you need
docker load -i myapp.tar

This creates fresh image layers without orphaned data.

4Extend the LVM thin pool

If your volume group has free space, extend the thin pool:

bash
# Check available space in the volume group
sudo vgs

# Extend the thin pool (adjust the path based on your setup)
sudo lvextend -l+100%FREE /dev/docker/thinpool

If the thin pool name is different, find it with:

bash
sudo lvs -a | grep pool

After extending, verify Docker recognizes the new space:

bash
docker info | grep "Data Space"
5Configure thin pool autoextend

Enable automatic thin pool extension to prevent future issues. Create or edit the LVM profile:

bash
sudo vi /etc/lvm/profile/docker-thinpool.profile

Add these settings:

bash
activation {
  thin_pool_autoextend_threshold=80
  thin_pool_autoextend_percent=20
}

This extends the pool by 20% when usage reaches 80%. Apply the profile:

bash
sudo lvchange --metadataprofile docker-thinpool docker/thinpool
6Adjust minimum free space setting (temporary workaround)

As a temporary fix, you can lower the minimum free space threshold:

bash
sudo systemctl stop docker

Edit or create /etc/docker/daemon.json:

json
{
  "storage-opts": [
    "dm.min_free_space=5%"
  ]
}

Restart Docker:

bash
sudo systemctl start docker

Warning: Lowering this threshold too much risks thin pool exhaustion and potential data corruption. Use this only as a temporary measure while implementing a permanent fix.

7Migrate to overlay2 storage driver (recommended)

The devicemapper driver is deprecated. Migrating to overlay2 provides better performance and avoids thin pool issues:

Warning: This process removes all existing images and containers. Back up important data first.

bash
# Stop Docker
sudo systemctl stop docker

# Back up Docker data (optional)
sudo cp -au /var/lib/docker /var/lib/docker.backup

# Remove old Docker data
sudo rm -rf /var/lib/docker

# Configure overlay2 in daemon.json
sudo vi /etc/docker/daemon.json

Set the storage driver:

json
{
  "storage-driver": "overlay2"
}

Start Docker:

bash
sudo systemctl start docker
docker info | grep "Storage Driver"

You'll need to re-pull all images after migration.

Advanced notes

Understanding thin pool architecture: Docker's devicemapper driver creates a thin pool with two components: a data volume for actual storage and a metadata volume for tracking allocations. Both can run out of space independently. Check both with sudo lvs -a.

Loopback vs direct-lvm: Loopback mode uses sparse files that can grow up to a fixed limit, while direct-lvm uses actual block devices. Loopback is easier to set up but has significant performance and reliability limitations. For production, always use direct-lvm or migrate to overlay2.

AWS/Cloud environments: On AWS Elastic Beanstalk, Docker environments provision a separate 12GB xvdcz volume for image storage by default. Customize this with BlockDeviceMapping configuration if you need more space.

RHEL/CentOS specific notes: Older versions defaulted to devicemapper. RHEL 7.4+ and CentOS 7.4+ support overlay2 with kernel 3.10.0-693 or later. Check compatibility with cat /proc/filesystems | grep overlay.

Recovery from severe thin pool exhaustion: If the thin pool is completely full (0 free blocks), you may need to:
1. Add a new physical volume to the volume group: sudo pvcreate /dev/sdX && sudo vgextend docker /dev/sdX
2. Then extend the thin pool
3. Or delete the Docker data directory entirely and start fresh

Monitoring: Set up monitoring for thin pool usage to catch issues before they cause failures:

bash
# Add to crontab or monitoring system
lvs --noheadings -o data_percent docker/thinpool

Frequently asked questions

What does "devmapper: Thin Pool has free data blocks which is less than minimum r" mean?
The "Thin Pool has free data blocks which is less than minimum required" error occurs when using Docker with the devicemapper storage driver. Docker maintains a minimum free space threshold in the thin pool to ensure safe operation. When free data blocks fall below this threshold, Docker prevents new operations to avoid data corruption.
How do I fix "devmapper: Thin Pool has free data blocks which is less than minimum r"?
This error occurs when Docker's devicemapper thin pool runs out of free data blocks. The fix involves cleaning up unused Docker resources, extending the thin pool, or migrating to the overlay2 storage driver.
What causes "devmapper: Thin Pool has free data blocks which is less than minimum r"?
Accumulated unused images and containers filling the thin pool Thin pool size configured too small for workload Autoextend disabled or not configured for the thin pool
Is the "devmapper: Thin Pool has free data blocks which is less than minimum r" 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