Notes on `failed to register layer: rename` error with docker pull.

docker failed to register layer: rename.md

📝 Docker's "failed to register layer" error on macOS/OrbStack.

Error Message

failed to register layer: rename /var/lib/docker/image/overlay2/layerdb/tmp/write-set-xxx /var/lib/docker/image/overlay2/layerdb/sha256 /<sha>: file exists

Reason

• Errors during docker pull leaving debris in layer.
  • This can happen when docker pull is performed when the disk space is full.

Solution

• Delete /var/lib/docker/image/overlay2/layerdb/sha256/<sha>

failed to register layer: rename <src> <dist>: file exists

Deleting the rubbish file in this <dist> dir will cure the problem, but this file is in Docker, In Docker for macOS, you can delete it by going into Docker and forcibly rm it.

$ docker run -it --rm --privileged --pid=host alpine:edge nsenter -t 1 -m -u -n -i rm -rf /var/lib/docker/image/overlay2/layerdb/sha256/<sha>

• Related: Getting a Shell in the Docker Desktop Mac VM

After deleting, this cache file will not be used from the next pull, so you will be able to pull.

The error itself probably occurs when there is insufficient disk space, so you should free up disk space before doing this.

Related.

• Docker failed to register layer - Stack Overflow