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· 167 views

This error occurs when Docker runs out of disk space while pulling images, building containers, or writing to volumes. The fix involves cleaning up unused Docker objects and ensuring adequate disk space.

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 volumes separately
  4. Clear the 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 "no space left on device" error in Docker indicates that the filesystem where Docker stores its data has run out of free space. Docker uses disk space to store images, containers, volumes, build cache, and other data in the /var/lib/docker directory by default on Linux (or a virtual disk on Docker Desktop for Mac/Windows). When this directory fills up, Docker operations fail with this error. The specific message "failed to register layer: Error processing tar file(exit status 1)" indicates that Docker cannot extract and register a new image layer because there's no room to write the uncompressed data. Docker takes a conservative approach to cleanup and doesn't automatically remove unused objects like stopped containers, dangling images, or orphaned volumes. Over time, these accumulate and can consume significant disk space, especially in development environments with frequent builds.

Typical symptoms

  • Docker pull fails with 'no space left on device'
  • Docker build fails during image layer extraction
  • Container creation fails unexpectedly
  • 'docker system df' shows high disk usage
  • Build cache consuming gigabytes of space
  • Many stopped containers or dangling images present

Common causes

  1. Docker build cache has accumulated over time
  2. Many unused/dangling images from previous builds
  3. Stopped containers still consuming disk space
  4. Unused volumes taking up space
  5. Docker data directory is on a small partition
  6. Large image being pulled requires more space than available (needs both compressed download and uncompressed extraction space)
  7. Running out of inodes (rare, but possible on some filesystems)

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

1Check Docker disk usage

First, see exactly how Docker is using disk space:

bash
docker system df

This shows space used by images, containers, volumes, and build cache. Add -v for verbose output:

bash
docker system df -v

Also check your system's available disk space:

bash
df -h
2Prune unused Docker objects

Remove all stopped containers, unused networks, dangling images, and build cache:

bash
docker system prune

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

bash
docker system prune -a

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

3Prune volumes separately

Volumes are NOT removed by docker system prune by default to prevent 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 in unused volumes. Make sure you don't need any data before running this.

4Clear the build cache

Docker's build cache can grow significantly with frequent builds. To clear it:

bash
docker builder prune

To remove all build cache (not just dangling entries):

bash
docker builder prune -a
5Remove specific unused resources

For more targeted cleanup:

Remove stopped containers:

bash
docker container prune

Remove dangling images:

bash
docker image prune

Remove all unused images:

bash
docker image prune -a

List and remove specific images:

bash
docker images
docker rmi <image_id>
6Verify space was freed and retry

Check that disk space was recovered:

bash
docker system df
df -h

Then retry your original Docker command (pull, build, etc.).

Advanced notes

Docker Desktop (Mac/Windows): If you're using Docker Desktop, you can increase the disk space limit through Settings > Resources > Advanced > Disk image size. On Mac, the Docker.raw file stores all Docker data. Sometimes deleting it and restarting Docker Desktop can resolve persistent issues (but you'll lose all images, containers, and volumes).

Moving Docker's data directory: If your root partition is small, you can move Docker's data to a larger partition by editing /etc/docker/daemon.json:

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

Then restart Docker: sudo systemctl restart docker

LVM environments: If you're using LVM and the volume is too small, expand it:

bash
lvextend -l 100%FREE /dev/mapper/ubuntu--vg-ubuntu--lv
resize2fs /dev/mapper/ubuntu--vg-ubuntu--lv

Inode exhaustion: In rare cases, you might have disk space but no inodes. Check with df -ih. Each file uses one inode, and many small Docker layers can exhaust inodes.

Devicemapper storage driver (RHEL/CentOS): The devicemapper driver has a 10GB per-image limit by default. Large images may fail even with available disk space. Consider switching to overlay2.

Prevention best practices:
- Run docker system prune regularly (weekly or after major builds)
- Use specific image tags instead of latest to avoid accumulating old versions
- Add --rm flag when running temporary containers: docker run --rm ...
- Set up a cron job for automated cleanup in CI/CD environments

Frequently asked questions

What does "failed to register layer: Error processing tar file(exit status 1): no" mean?
The "no space left on device" error in Docker indicates that the filesystem where Docker stores its data has run out of free space. Docker uses disk space to store images, containers, volumes, build cache, and other data in the /var/lib/docker directory by default on Linux (or a virtual disk on Docker Desktop for Mac/Windows). When this directory fills up, Docker operations fail with this error.
How do I fix "failed to register layer: Error processing tar file(exit status 1): no"?
This error occurs when Docker runs out of disk space while pulling images, building containers, or writing to volumes. The fix involves cleaning up unused Docker objects and ensuring adequate disk space.
What causes "failed to register layer: Error processing tar file(exit status 1): no"?
Docker build cache has accumulated over time Many unused/dangling images from previous builds Stopped containers still consuming 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