Skip to content

Instantly share code, notes, and snippets.

@johnlane
Created April 23, 2022 10:31
Show Gist options
  • Save johnlane/68711bdeca0f1b480b0414eb5f2368ec to your computer and use it in GitHub Desktop.
Save johnlane/68711bdeca0f1b480b0414eb5f2368ec to your computer and use it in GitHub Desktop.

The file not allowed in a Docker image

You cannot have a file in a Docker image with a name that starts with .wh.. Try this:

$ echo "files beginning .wh. are not allowed!" > test.txt
$ echo -e "FROM alpine:latest\nCOPY test.txt /.wh.test.txt" > Dockerfile
$ docker build -t johnlane/wontwork:latest .

It builds ok, but the file isn't there:

$ docker run -i --rm johnlane/wontwork:latest ls /.wh.test.txt
ls: /.wh.test.txt: No such file or directory

You can't save the image:

$ docker save johnlane/wontwork:latest -o wontwork.tar
Error response from daemon: open /var/lib/docker/zfs/graph/e9a10c904c15605f42bb10c2b8e905eaa16645190e3a0d4486fe794d2dfafd2b/.wh.test.txt: no such file or directory

And trying to push it will see it retrying endlessly:

$ docker login -u johnlane
$ docker push johnlane/wontwork:latest
The push refers to repository [docker.io/johnlane/wontwork]
fd960c7c0fdd: Retrying in 4 seconds
4fc242d58285: Layer already exists

Strange though this may seem, it isn't a bug. It's due to how deleted files are represented in image layers and is described by the spec

for each deleted item an entry for an empty file at the same location but with the basename of the deleted file or directory prefixed with .wh.. The filenames prefixed with .wh. are known as "whiteout" files. NOTE: For this reason, it is not possible to create an image root filesystem which contains a file or directory with a name beginning with .wh..

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment