How to fix failed to register layer: Error processing tar file(exit status 1): no space left on device in Docker

DockerBEGINNERHIGHUpdated Dec 6, 2025· 166 views

This error occurs when Docker cannot extract and register image layers due to insufficient disk space on the host filesystem. The solution involves cleaning up unused Docker resources or expanding available storage.

Quick fix

Fixes failed to register layer: Error processing tar file(exit status 1): no space left on device

docker system df
  1. Check Docker disk usage
  2. Prune unused Docker objects
  3. Prune Docker volumes
  4. Clear Docker build cache
docker — error
docker system df
failed to register layer: Error processing tar file(exit status 1): no space left on device

What this error means

The "failed to register layer: Error processing tar file(exit status 1): no space left on device" error indicates that Docker has exhausted the available disk space while attempting to extract and register a new image layer. Docker stores all its data, including images, containers, volumes, and build cache, in a specific directory (typically /var/lib/docker on Linux or within a virtual disk on Docker Desktop for Mac/Windows). When you pull an image or build a container, Docker downloads compressed layers and then extracts them. This extraction process requires additional free space beyond the compressed size because Docker needs room to write the uncompressed data. If the filesystem runs out of space during this extraction, the operation fails with this specific error. Docker does not automatically clean up unused resources like stopped containers, dangling images, or orphaned volumes. Over time, these accumulate and can consume tens of gigabytes of disk space, especially in development environments where images are frequently rebuilt or pulled.

Typical symptoms

  • Docker pull commands fail with 'no space left on device' error
  • Docker build fails during layer extraction with exit status 1
  • Container creation fails unexpectedly mid-process
  • 'docker system df' shows high disk usage across images, containers, or build cache
  • Build cache has accumulated gigabytes of data
  • Multiple stopped containers and dangling images are present
  • Error occurs specifically during 'registering layer' phase

Common causes

  1. Docker build cache has accumulated significantly over time
  2. Many unused or dangling images from previous builds consuming space
  3. Stopped containers that were never removed still using disk space
  4. Unused Docker volumes occupying storage
  5. Docker data directory (/var/lib/docker) is on a partition with limited space
  6. Large images require more space than available for both download and extraction
  7. Container log files have grown excessively large
  8. Inode exhaustion on the filesystem (rare but possible)

How to fix "failed to register layer: Error processing tar file(exit status 1): no space left on device"

1Check Docker disk usage

First, analyze how Docker is consuming disk space:

bash
docker system df

This displays space used by images, containers, volumes, and build cache. For detailed breakdown:

bash
docker system df -v

Also verify your host system's available disk space:

bash
df -h

Look for the partition containing /var/lib/docker (or Docker Desktop's virtual disk).

2Prune unused Docker objects

Remove all stopped containers, unused networks, dangling images, and build cache with a single command:

bash
docker system prune

For a more aggressive cleanup that also removes ALL unused images (not just dangling ones):

bash
docker system prune -a

Add -f to skip the confirmation prompt:

bash
docker system prune -a -f

Warning: The -a flag removes ALL images not currently used by running containers. You will need to re-pull or rebuild them later.

3Prune Docker volumes

By default, docker system prune does NOT remove volumes to prevent accidental data loss. To remove unused volumes:

bash
docker volume prune

Or include volumes in the system prune:

bash
docker system prune --volumes

Warning: This permanently deletes data stored in unused volumes. Ensure you have backups of any important data before running this command.

4Clear Docker build cache

Docker's BuildKit cache can grow substantially with frequent builds. To clear it:

bash
docker builder prune

To remove ALL build cache entries (not just dangling ones):

bash
docker builder prune -a

This is especially effective if you've been doing many iterative builds during development.

5Remove specific unused resources

For more targeted cleanup when you want finer control:

Remove only stopped containers:

bash
docker container prune

Remove only dangling images:

bash
docker image prune

Remove ALL unused images:

bash
docker image prune -a

List and selectively remove images:

bash
docker images
docker rmi <image_id_or_name>

Remove unused networks:

bash
docker network prune
6Truncate container log files

Container logs can consume significant space. To truncate logs for a specific container:

bash
# Find the container ID
docker ps -a

# Truncate its log file (requires root/sudo)
sudo truncate -s 0 /var/lib/docker/containers/<container_id>/<container_id>-json.log

To prevent future log growth, configure log rotation in your Docker daemon config (/etc/docker/daemon.json):

json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Then restart Docker: sudo systemctl restart docker

7Verify space recovery and retry

Confirm that disk space has been recovered:

bash
docker system df
df -h

Then retry your original Docker command:

bash
docker pull <image_name>
# or
docker build -t <tag> .

The operation should now complete successfully.

Advanced notes

Docker Desktop (Mac/Windows): If using Docker Desktop, you can increase the virtual disk size through Settings > Resources > Advanced > Disk image size (called "Disk usage limit" in newer versions). On macOS, the Docker.raw or Docker.qcow2 file in ~/Library/Containers/com.docker.docker/Data/vms/ stores all Docker data. Deleting this file and restarting Docker Desktop will reset Docker to a clean state, but you will lose all images, containers, and volumes.

Moving Docker's data directory: If your root partition is consistently low on space, relocate Docker's data to a larger partition by creating or editing /etc/docker/daemon.json:

json
{
  "data-root": "/path/to/larger/partition/docker"
}

Then stop Docker, move existing data, and restart:

bash
sudo systemctl stop docker
sudo mv /var/lib/docker /path/to/larger/partition/docker
sudo systemctl start docker

LVM-based storage: If using LVM and your volume is too small, expand it:

bash
# Extend the logical volume
sudo lvextend -l +100%FREE /dev/mapper/your-vg-your-lv
# Resize the filesystem
sudo resize2fs /dev/mapper/your-vg-your-lv

Inode exhaustion: In rare cases, you might have available disk space but no inodes. Check with df -ih. Each file uses one inode, and Docker's many small layer files can exhaust inodes on some filesystems.

Storage driver considerations: The overlay2 storage driver (default on modern systems) is efficient, but older systems using devicemapper may have a 10GB per-image limit by default. Check your storage driver with docker info | grep "Storage Driver".

CI/CD environments: In automated pipelines, add cleanup steps:

yaml
# Example for GitHub Actions
- name: Clean up Docker
  run: docker system prune -af --volumes

Prevention best practices:
- Run docker system prune weekly or after major development sessions
- Use specific image tags instead of latest to avoid accumulating old versions
- Always use --rm flag for temporary containers: docker run --rm ...
- Configure log rotation to prevent unbounded log growth
- Monitor /var/lib/docker disk usage with alerting in production environments

Frequently asked questions

What does "failed to register layer: Error processing tar file(exit status 1): no" mean?
The "failed to register layer: Error processing tar file(exit status 1): no space left on device" error indicates that Docker has exhausted the available disk space while attempting to extract and register a new image layer. Docker stores all its data, including images, containers, volumes, and build cache, in a specific directory (typically /var/lib/docker on Linux or within a virtual disk on Docker Desktop for Mac/Windows). When you pull an image or build a container, Docker downloads compressed layers and then extracts them.
How do I fix "failed to register layer: Error processing tar file(exit status 1): no"?
This error occurs when Docker cannot extract and register image layers due to insufficient disk space on the host filesystem. The solution involves cleaning up unused Docker resources or expanding available storage.
What causes "failed to register layer: Error processing tar file(exit status 1): no"?
Docker build cache has accumulated significantly over time Many unused or dangling images from previous builds consuming space Stopped containers that were never removed still using disk space
Is the "failed to register layer: Error processing tar file(exit status 1): no" 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