🐳 Docker Error Guide: 'ApplyLayer lchown operation not permitted' Image Extract Failure

Exact Error Message

failed to register layer: ApplyLayer exit status 1 stdout:  stderr:
lchown /usr/bin/passwd: operation not permitted

You may also see it phrased as an unpack error during a pull:

Error processing tar file(exit status 1): lchown /var/log: operation not permitted

Both occur while Docker is extracting an image layer to disk, and both fail on the same syscall: lchown.

What It Means

When Docker unpacks an image layer, it recreates every file with the ownership recorded in the tar archive, using the lchown syscall to set each file’s UID/GID (including on symlinks). operation not permitted means the process doing the extraction is not allowed to change a file’s owner to the UID the layer requires.

This is almost always a privilege or UID-mapping problem, not a corrupt image. In rootless Docker or when user namespace remapping (userns-remap) is active, the daemon runs inside a restricted UID range; if a layer wants to set an owner outside your mapped subordinate UID/GID range, lchown is refused. The same refusal happens when the storage directory sits on a filesystem that cannot honor ownership changes (some network shares, or a nosuid/mapped mount), or when /etc/subuid and /etc/subgid do not grant a wide enough range.

Common Causes

• Rootless Docker with an insufficient subordinate UID/GID range in /etc/subuid / /etc/subgid.
• userns-remap enabled but the remap user lacks a large enough mapped range for the layer’s owners.
• Docker data root on a filesystem that cannot change ownership (NFS/CIFS, or a bind mount with restrictive options).
• The overlay2 storage driver unavailable, forcing a fallback (like vfs) on a filesystem that rejects lchown.
• Running the daemon or build under a constrained UID that cannot chown to arbitrary IDs.

Diagnostic Commands

Confirm whether you are running rootless or remapped, and which storage driver is active:

docker info | grep -E 'rootless|Storage Driver|Data Root'

Check the subordinate UID/GID ranges available to your user:

grep "$(whoami)" /etc/subuid /etc/subgid

Identify the filesystem backing Docker’s data root:

findmnt -T "$(docker info -f '{{.DockerRootDir}}')"

Reproduce the failure verbosely to see exactly which path fails lchown:

docker pull node:20-alpine

Step-by-Step Resolution

1. For rootless Docker, ensure your subordinate ID ranges are large enough (at least 65536). Add or widen the entries, then restart the rootless daemon:

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 "$(whoami)"
systemctl --user restart docker

2. If /etc/subuid//etc/subgid were empty or tiny, that alone causes the error. After fixing them, the rootless daemon must re-create its namespace:

docker info | grep rootless

3. For userns-remap on rootful Docker, verify the remap user has a full range in /etc/subuid and /etc/subgid, then restart:

grep dockremap /etc/subuid /etc/subgid
sudo systemctl restart docker

4. Move Docker’s data root off a filesystem that cannot honor ownership changes. Point it at a local ext4/xfs volume in /etc/docker/daemon.json:

{
  "data-root": "/var/lib/docker",
  "storage-driver": "overlay2"
}

sudo systemctl restart docker

5. Confirm overlay2 is in use rather than a vfs fallback, since vfs on a mapped or network filesystem commonly triggers lchown refusals:

docker info -f '{{.Driver}}'

6. If a specific bind-mounted data directory is the problem, remount it without options that block ownership changes, or relocate it to local disk.

7. Retry the pull or build and confirm the layers extract cleanly:

docker pull node:20-alpine

Status: Downloaded newer image for node:20-alpine

Prevention

• Provision at least a 65536-wide subordinate UID/GID range for any user running rootless Docker.
• Keep Docker’s data root on a local overlay2-capable filesystem (ext4/xfs), not NFS/CIFS.
• When enabling userns-remap, verify the dockremap user’s /etc/subuid//etc/subgid entries before restarting.
• Avoid the vfs storage driver except for testing; ensure overlay2 prerequisites are met so Docker does not fall back.
• Test base images in your rootless/remapped environment early, since some layers set unusual owners. For generating rootless-safe Dockerfiles and daemon configs, see the DevOps AI prompt library.

Related Errors

• Error processing tar file(exit status 1): lchown ...: operation not permitted — the same failure during a pull’s unpack phase.
• there might not be enough IDs available in the namespace (requested X:Y) — the explicit range-too-small message under userns.
• failed to register layer: Error processing tar file: operation not permitted — a broader permission failure on the same extraction step.
• no space left on device — a disk cause of layer-registration failures, distinct from lchown.

Frequently Asked Questions

Why does lchown fail only in rootless Docker? Rootless mode runs inside a user namespace with a limited subordinate UID/GID range. If an image layer sets ownership to a UID outside your mapped range, the kernel refuses the lchown. Widening /etc/subuid and /etc/subgid to 65536 fixes most cases.

Is the image corrupted? Almost never. The layer is fine; your environment cannot apply the ownership it records. The fix is UID mapping or the storage filesystem, not re-pulling the image.

Can this happen on NFS or a network share? Yes. Many network and specially-mounted filesystems cannot honor arbitrary ownership changes, so lchown is denied during extraction. Move Docker’s data root to local disk with overlay2.

What subuid/subgid range should I allocate? Grant at least 65536 IDs (for example 100000-165535) so layers using high or unusual UIDs can be mapped. Restart the rootless or remapped daemon after changing the ranges. For more, see the Docker guides.