🚨 Docker Error Guide: 'failed to register layer' Storage and Layer Extraction Failures

Exact Error Message

failed to register layer appears at the end of a pull, while Docker is extracting a downloaded layer onto the storage driver. The suffix tells you which underlying failure occurred:

failed to register layer: write /usr/lib/.../libfoo.so: no space left on device

failed to register layer: Container ID 165535 cannot be mapped to a host ID

failed to register layer: ApplyLayer exit status 1 stdout:  stderr: lchown /var/lib/docker/overlay2/.../etc/shadow: operation not permitted

failed to register layer: ApplyLayer exit status 1 stdout:  stderr: archive/tar: invalid tar header

The layer downloaded fine; the failure is in writing it to disk. The text after failed to register layer: is the real diagnosis.

What It Means

A Docker image is a stack of tar layers. After downloading each compressed layer, the daemon unpacks it onto the storage driver (usually overlay2 under /var/lib/docker), recreating files with their original ownership and permissions. “Register layer” is this extract-and-commit step. It fails when the filesystem cannot hold the files (no space left on device), when ownership cannot be applied (lchown/userns mapping), or when the layer’s tar stream is malformed (invalid tar header). The image is left incomplete and the pull aborts.

Because the download itself usually succeeds, this error is misleading: engineers re-check the registry and credentials when the real problem is local to the host’s disk, storage driver, or user-namespace configuration. The fix almost always lives under /var/lib/docker and in the daemon log, not in the registry.

Common Causes

• Disk full. /var/lib/docker (or its partition) is out of bytes — no space left on device.
• Inode exhaustion. The partition has free bytes but no free inodes; many small files in images can exhaust them, also surfacing as no space left on device.
• overlay2 corruption. A previous crash or unclean shutdown left stale/partial directories under overlay2, so a new layer cannot be committed.
• userns-remap chown failures. With userns-remap enabled, a layer file owner outside the configured subuid/subgid range cannot be mapped — Container ID ... cannot be mapped to a host ID.
• lchown operation not permitted. The daemon lacks privilege to set ownership (e.g. running on a filesystem mounted nosuid/restrictive, or rootless without proper subuid setup).
• Corrupted or truncated layer download. A flaky network or registry produced a bad tar stream — invalid tar header / ApplyLayer exit status 1.
• Kernel/overlay limits. Unsupported backing filesystem or overlay-on-overlay nesting the kernel rejects.

How to Reproduce the Error

Fill the Docker partition, then pull a large image:

fallocate -l $(df --output=avail -B1 /var/lib/docker | tail -1) /var/lib/docker/fill.tmp
docker pull ubuntu:24.04

failed to register layer: write /var/lib/docker/overlay2/.../bin/bash: no space left on device

(Remove fill.tmp afterward.)

Diagnostic Commands

Start with Docker’s own space accounting:

docker system df

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          84        12        41.2GB    33.8GB (82%)
Build Cache     920       0         18.6GB    18.6GB

Then check the host partition for both bytes and inodes — inode exhaustion is the trap:

df -h /var/lib/docker
df -i /var/lib/docker

Filesystem      Size  Used Avail Use% Mounted on
/dev/nvme0n1p1  100G  100G    0G 100% /
Filesystem      Inodes  IUsed  IFree IUse% Mounted on
/dev/nvme0n1p1  6.5M    6.5M     0   100% /

See what is consuming /var/lib/docker and read the daemon log for the precise failure:

du -sh /var/lib/docker/* | sort -rh | head
journalctl -u docker --since "10 min ago" | grep -i 'register layer\|space\|lchown\|map'

For userns or tar errors, the daemon log shows the mapping or header line that the CLI truncated. Confirm whether userns-remap is on:

docker info | grep -iA1 'userns\|Storage Driver'

Step-by-Step Resolution

Cause: disk full. Reclaim space, starting with the build cache and dangling images, then re-pull:

docker builder prune -f
docker system prune -a -f
df -h /var/lib/docker
docker pull ubuntu:24.04

If the partition is still tight, move /var/lib/docker to a larger volume (set data-root in /etc/docker/daemon.json) or grow the disk. See the no space left on device guide for the full storage cleanup.

Cause: inode exhaustion. prune frees inodes too. If a non-Docker process holds them, find and clear those files; reformatting the volume with more inodes is the last resort.

Cause: overlay2 corruption. Stop the daemon, remove the orphaned layer dirs flagged in the log (or, as a heavy reset, clear overlay2 after backing up needed images), and re-pull:

systemctl stop docker
# inspect the offending path from journalctl first
systemctl start docker
docker pull ubuntu:24.04

Cause: userns-remap mapping. Widen the subuid/subgid range so all layer owners map, then restart Docker:

grep dockremap /etc/subuid /etc/subgid
# ensure a range like dockremap:165536:65536 in both files
systemctl restart docker

If you do not need userns isolation for this host, removing "userns-remap" from daemon.json also clears the mapping failure.

Cause: lchown operation not permitted. Ensure /var/lib/docker is on a filesystem that allows ownership changes (not a restrictive bind/nosuid mount), and that the daemon runs with sufficient privilege. For rootless Docker, fix the user’s subuid/subgid setup.

Cause: corrupted/truncated layer (invalid tar header). Clear the partial download and re-pull; if it recurs, the registry copy is bad:

docker rmi ubuntu:24.04 2>/dev/null
docker pull ubuntu:24.04

A worked example. A build node starts failing every pull with failed to register layer: write ...: no space left on device, but df -h shows 30 GB free. The trap here is inodes, not bytes:

df -i /var/lib/docker

Filesystem      Inodes  IUsed IFree IUse% Mounted on
/dev/nvme0n1p1  6.5M    6.5M    0   100% /

Inodes are exhausted by the many tiny files in accumulated build cache and image layers. docker builder prune -f followed by docker image prune -a -f reclaims tens of thousands of inodes, df -i drops back below 60%, and pulls succeed again. Always check both df -h and df -i — a “no space” error with free bytes is almost always inode exhaustion.

How to Prevent the Issue

• Monitor both df -h and df -i on the Docker partition and alert well before 100%.
• Schedule docker system prune / builder prune so build cache and dangling images cannot fill the disk.
• Put /var/lib/docker on a dedicated, generously sized volume with a supported backing filesystem (ext4/xfs with ftype=1).
• Configure userns-remap subuid/subgid ranges to cover all expected layer owners before enabling it cluster-wide.
• Pull over reliable networks and use a pull-through cache/mirror to reduce truncated-layer corruption.

Related Docker Errors

• Docker Error Guide: ‘no space left on device’ — the dedicated guide to reclaiming Docker storage.
• Docker Error Guide: ‘manifest unknown’ — a registry-side failure that aborts the pull before any layer is registered.
• See more Docker troubleshooting guides.