Docker invalid reference format: repository name must be lowercase


Invalid reference format means that docker wants to access an image but couldn’t. This could be due to a number of reasons like the repository doesn’t exist or url is wrong. But in this case, the error says that repository name must be lowercase. It means there are uppercase characters in the repository name, somewhere.

This includes the complete path and not just image name. Your repository address as well as image name need to be in all lowercase.

Reasons of this error

Here docker is complaining about repository name not in lowercase, but the reasons could be different. What if the image name is already in lowercase and still you are getting this error?

We have already covered reasons for docker invalid reference format in previous article. So, here we will focus on repository name issue only.


These are the examples of invalid repository names –

  • myImage:latest ❌
  • myImage ❌
  • myImage:v23 ❌
  • Mysql:v5.6.7 ❌
  • FROM Ubuntu (in Dockerfile) ❌
  • MYIMAGE:latest ❌
  • myimage:Latest ❌
  • my image:latest ❌
  • ❌
  • ❌

The correct formats are –

  • myimage:latest ✔️
  • myimage ✔️
  • myimage:v23 ✔️
  • mysql:v5.6.7 ✔️
  • FROM ubuntu (in Dockerfile) ✔️
  • myimage:latest ✔️
  • myimage:latest ✔️
  • myimage:latest ✔️
  • ✔️

This rule works with Dockerfile as well as terminal commands. Always keep your reference variables like $(pwd) under quotes. Like this – "$(pwd)". Unless you are referencing some integer value.

When there are blank spaces in the values of these variables, the commands break down partially.

Also, check whether you are using such command in your Dockerfile –

FROM Base as Build
# or

You need to keep the name Base, Build, PROD, Dev in lowercase –

FROM base as build
FROM prod as dev

Another thing you need to check is whether the reference variables are set or not. Sometimes we forget to set variables like $(pwd) and start using them in Dockerfile. You need to set them before using.


Invalid reference format error could raise due to number of reasons in docker. One of them is repository name not in lowercase. In this article we saw where to pay attention and what are the major areas of error.