Docker error: invalid reference format: repository

Question

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.

Answer 1

For me the issue was with the space in volume mapping that was not escaped. The jenkins job which was running the docker run command had a space in it and as a result docker engine was not able to understand the docker run command.

Answer 2

A reference in Docker is what points to an image. This could be in a remote registry or the local registry. Let me describe the error message first and then show the solutions for this.

invalid reference format

This means that the reference we have used is not a valid format. This means, the reference (pointer) we have used to identify an image is invalid. Generally, this is followed by a description as follows. This will make the error much clearer.

invalid reference format: repository name must be lowercase

This means the reference we are using should not have uppercase letters. Try running docker run Ubuntu (wrong) vs docker run ubuntu (correct). Docker does not allow any uppercase characters as an image reference. Simple troubleshooting steps.

1) Dockerfile contains a capital letters as images.

FROM Ubuntu (wrong)
FROM ubuntu (correct)

2) Image name defined in the docker-compose.yml had uppercase letters

3) If you are using Jenkins or GoCD for deploying your docker container, please check the run command, whether the image name includes a capital letter.

Please read this document written specifically for this error.

Answer 3

"docker build -f Dockerfile -t SpringBoot-Docker ." As in the above commend, we are creating an image file for docker container. commend says create image use file(-f refer to docker file) and -t for the target of the image file we are going to push to docker. the "." represents the current directory

solution for the above problem: provide target image name in lowercase

Answer 4

Docker can build images automatically by reading the instructions from a Dockerfile. A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image. example: FROM python:3.7-alpine The 'python' should be in lowercase

Answer 5

In my case I was trying to run postgres through docker. Initially I was running as :

docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=test_password POSTGRES_USER=test_user POSTGRES_DB=test_db --rm -v ~/docker/volumes/postgres:/var/lib/postgresql/data --name pg-docker postgres

I was missing -e after each environment variable. Changing the above command to the one below worked

docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=test_password -e POSTGRES_USER=test_user -e POSTGRES_DB=test_db --rm -v ~/docker/volumes/postgres:/var/lib/postgresql/data --name pg-docker postgres

Answer 6

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. With a compose file, if you expand a variable in the image name, that variable may not be expanding correctly.

With the docker run command line, this is often the result in not quoting parameters with spaces, 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

And the fix is as easy as:

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