Error AtlasError Documentation and Resolution
Back to searchMore Docker errors

Docker

Docker failed to register layer because lchown returned invalid argument

docker: failed to register layer: Error processing tar file(exit status 1): lchown <FILE>: invalid argument

Docker could not register an image layer during pull because the rootless environment does not have enough subuid or subgid entries for the image being unpacked.

failed to register layerinstallation

Observed message

docker: failed to register layer: Error processing tar file(exit status 1): lchown <FILE>: invalid argument

Why it happens

  • The rootless Docker setup does not have enough entries in /etc/subuid or /etc/subgid.
  • The image requires more UID or GID mappings than the current configuration provides.

How to fix it

  1. Increase the number of available entries in /etc/subuid and /etc/subgid.
  2. Use a rootless configuration that provides at least the recommended mapping range for most images.
  3. Retry the pull after updating the user namespace configuration.

Official reference

Docker Docs: Rootless troubleshooting

Related errors

Docker.app is damaged and can't be openedDocker Desktop on macOS reported Docker.app is damagedIncompatible CPU detectedDocker Desktop reported an incompatible CPU on macOSfailed to register layerDocker failed to register layer because lchown returned operation not permittedfailed to solveDocker build failed to solve

Explore more

DockerBrowse more Docker errorsinstallationBrowse more installation errors
Docker failed to register layer lchown invalid argument: fixes | Error Atlas