Docker error: invalid reference format: repository name must be lowercase

Ran into this Docker error with one of my projects:

invalid reference format: repository name must be lowercase

What are the various causes for this generic message?

I already figured it out after some effort, so I'm going to answer my own question in order to document it here as the solution doesn't come up right away when doing a web search and also because this error message doesn't describe the direct problem Docker encounters.

Solution 1:

A "reference" in docker is a pointer to an image. It may be an image name, an image ID, include a registry server in the name, use a sha256 tag to pin the image, and anything else that can be used to point to the image you want to run.

The invalid reference format error message means docker cannot convert the string you've provided to an image. This may be an invalid name, or it may be from a parsing error earlier in the docker run command line if that's how you run the image.

If the name itself is invalid, the repository name must be lowercase means you use upper case characters in your registry or repository name, e.g. YourImageName:latest should be yourimagename:latest.

With the docker run command line, this is often the result in not quoting parameters with spaces, missing the value for an argument, and mistaking the order of the command line. The command line is ordered as:

docker ${args_to_docker} run ${args_to_run} image_ref ${cmd_to_exec}

The most common error in passing args to the run is a volume mapping expanding a path name that includes a space in it, and not quoting the path or escaping the space. E.g.

docker run -v $(pwd):/data image_ref

Where if you're in the directory /home/user/Some Project Dir, that would define an anonymous volume /home/user/Some in your container, and try to run Project:latest with the command Dir:/data image_ref. And the fix is to quote the argument:

docker run -v "$(pwd):/data" image_ref

Other common places to miss quoting include environment variables:

docker run -e SOME_VAR=Value With Spaces image_ref

which docker would interpret as trying to run the image With:latest and the command Spaces image_ref. Again, the fix is to quote the environment parameter:

docker run -e "SOME_VAR=Value With Spaces" image_ref

With a compose file, if you expand a variable in the image name, that variable may not be expanding correctly. So if you have:

version: 2
services:
  app:
    image: ${your_image_name}

Then double check that your_image_name is defined to an all lower case string.

Solution 2:

Let me emphasise that Docker doesn't even allow mixed characters.

Good: docker build -t myfirstechoimage:0.1 .

Bad: docker build -t myFirstEchoImage:0.1 .

Solution 3:

In my case was the -e before the parameters for mysql docker

docker run --name mysql-standalone -e MYSQL_ROOT_PASSWORD=hello -e MYSQL_DATABASE=hello -e MYSQL_USER=hello -e MYSQL_PASSWORD=hello -d mysql:5.6

Check also if there are missing whitespaces

Solution 4:

had a space in the current working directory and usign $(pwd) to map volumes. Doesn't like spaces in directory names.