227

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.

1
  • "reference" in this error message is the identifier of an image, as BMitch explained in his answer. So the format of the value you used to point to an image is invalid. Read BMitch's full explanation: stackoverflow.com/a/52818152/336694 Commented Apr 5, 2019 at 16:28

31 Answers 31

242

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.

5
  • 14
    "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" This was really helpful
    – user979899
    Commented Mar 10, 2020 at 11:14
  • 3
    The section explaining the need to quote the path docker run -v "$(pwd):/data" image_ref helped in my case.
    – BTR Naidu
    Commented Mar 9, 2022 at 22:20
  • 1
    This helped a lot, thanks! For anyone passing multiple environment variables to Docker, be aware that each var should receive their own "-e": docker run -e "env_var1=value1" -e "env_var2=value2" image_name
    – LucianoBAF
    Commented Aug 16, 2022 at 22:36
  • The problem here is that it is lower case, I'm not using any upper case letters anywhere in the image name and it's still giving me this error. Commented Nov 30, 2022 at 17:35
  • @NathanMcKaskle you are likely looking at a different part of the command than docker is. The first thing that is not a parameter to a flag is treated as the image name, and the CLI is separated by spaces.
    – BMitch
    Commented Nov 30, 2022 at 17:47
67

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

3
  • 12
    Same with me, I was missing the -e before one of my environment variables. Commented Jan 20, 2020 at 23:17
  • in my case I forgot to export variable from external environment. Commented Mar 13, 2020 at 13:32
  • It was the missing whitspaces between -e and another variable.
    – user42
    Commented Jan 19, 2023 at 10:01
49

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 .

1
  • 2
    I am using "spotify" maven dependency in the SpringBoot project to build the docker image and from the last couple of hours, I was struggling to understand the issue. The name of the project (contains capital characters) to turn out to be the issue! Commented Jun 2, 2020 at 0:18
30

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

3
  • 4
    That solved it for me! I wrapped $(pwd) in quotes and it worked. Commented Oct 24, 2019 at 15:59
  • For me, I had to escape any space characters.
    – vpap
    Commented Mar 1, 2022 at 17:30
  • Uppercase letters in the working directory also causes this issue. rename the working directory to all lowercase letters. Commented Aug 4, 2022 at 15:41
12

In my case, the image name defined in docker-compose.yml contained uppercase letters. The fact that the error message mentioned repository instead of image did not help describe the problem and it took a while to figure out.

2
  • 3
    Another common cause found by searching the web was that people have space characters in their directory names when mounting volumes. Commented Jan 30, 2018 at 13:31
  • 1
    It happened to me for a different reason. The docker multi-stage build inside a Dockerfile as named with upper letters. Example: FROM bla:bla AS BUILD failed. FROM bla:bla AS build was OK Thx! Commented Jan 18, 2019 at 15:12
11

In my case the problem was in parameters arrangement. Initially I had --name parameter after environment parameters and then volume and attach_dbs parameters, and image at the end of command like below.

docker run -p 1433:1433 -e sa_password=myComplexPwd -e ACCEPT_EULA=Y --name sql1 -v c:/temp/:c:/temp/ attach_dbs="[{'dbName':'TestDb','dbFiles':['c:\\temp\\TestDb.mdf','c:\\temp\\TestDb_log.ldf']}]" -d microsoft/mssql-server-windows-express

After rearranging the parameters like below everything worked fine (basically putting --name parameter followed by image name).

docker run -d -p 1433:1433 -e sa_password=myComplexPwd -e ACCEPT_EULA=Y --name sql1 microsoft/mssql-server-windows-express -v C:/temp/:C:/temp/ attach_dbs="[{'dbName':'TestDb','dbFiles':['C:\\temp\\TestDb.mdf','C:\\temp\\TestDb_log.ldf']}]"
7

On MacOS when your are working on an iCloud drive, your $PWD will contain a directory "Mobile Documents". It does not seem to like the space!

As a workaround, I copied my project to local drive where there is no space in the path to my project folder.

I do not see a way you can get around changnig the default path to iCloud which is ~/Library/Mobile Documents/com~apple~CloudDocs

The space in the path in "Mobile Documents" seems to be what docker run does not like.

1
  • 2
    Instead of copying the project, you can escape the space e.g. Mobile\ Documents
    – ogie
    Commented Feb 18, 2019 at 22:48
4

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.

3

sometimes you miss -e flag while specific multiple env vars inline

e.g. bad: docker run --name somecontainername -e ENV_VAR1=somevalue1 ENV_VAR2=somevalue2 -d -v "mypath:containerpath" <imagename e.g. postgres>

good: docker run --name somecontainername -e ENV_VAR1=somevalue1 -e ENV_VAR2=somevalue2 -d -v "mypath:containerpath" <imagename e.g. postgres>

1
  • "sometimes you miss -e flag" absolutely. Docker should come up with a more meaningful error message. Commented Apr 10 at 8:33
3

I've encountered the same issue while using docker with mlflow.

In my case, the directory name containing my Dockerfile was "My Project" which I changed to myproject or my_project and It worked for me.
Also, follow the same naming format for all the root/super directories under which, the Dockerfile resides.

Not only for docker, but it's also good practice (especially in Unix based OS) to avoid the following while defining a directory name:-

  • white spaces
  • camel-case
  • upper-case
3

If you encounter this problem in go-swagger (Windows).

@echo off
echo.
docker run --rm -it --env GOPATH=/go -v %CD%:/go/src -w /go/src quay.io/goswagger/swagger %*

Use this instead: (add quote)

@echo off
echo.
docker run --rm -it --env GOPATH=/go -v "%CD%:/go/src" -w /go/src quay.io/goswagger/swagger %*
2

Replacing image: ${DOCKER_REGISTRY}notificationsapi with image:notificationsapi or image: ${docker_registry}notificationsapi in docker-compose.yml did solves the issue

file with error

  version: '3.4'

services:
  notifications.api:
    image: ${DOCKER_REGISTRY}notificationsapi
    build:
      context: .
      dockerfile: ../Notifications.Api/Dockerfile

file without error

version: '3.4'

services:
 notifications.api:
    image: ${docker_registry}notificationsapi
    build:
      context: .
      dockerfile: ../Notifications.Api/Dockerfile

So i think error was due to non lower case letters it had

1
  • Great! In my case, my service was called frontendDev so I renamed it to frontend.dev and everything works again :) Commented Jul 21, 2023 at 19:57
2

In my case I had a naked --env switch, i.e. one without an actual variable name or value, e.g.:

docker run \
   --env \       <----- This was the offending item
   --rm \
   --volume "/home/shared:/shared" "$(docker build . -q)"
2

If you come here after encountering this error in your GitHub Actions worflows…

Make sure to use docker/metadata-action action to handle repository naming for you. Just call it before docker/build-push-action:

# Add this
- id: docker-metadata
  uses: docker/metadata-action@v4
  with:
    images: ghcr.io/${{ github.repository }}

# Use the extracted metadata
- uses: docker/build-push-action@v3
  with:
    tags: ${{ steps.docker-metadata.outputs.tags }}
    labels: ${{ steps.docker-metadata.outputs.labels }}
    … other properties …
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.

1

Indeed, the docker registry as of today (sha 2e2f252f3c88679f1207d87d57c07af6819a1a17e22573bcef32804122d2f305) does not handle paths containing upper-case characters. This is obviously a poor design choice, probably due to wanting to maintain compatible with certain operating systems that do not distinguish case at the file level (ie, windows).

If one authenticates for a scope and tries to fetch a non-existing repository with all lowercase, the output is

(auth step not shown)
curl -s -H "Authorization: Bearer $TOKEN" -X GET https://$LOCALREGISTRY/v2/test/someproject/tags/list
{"errors":[{"code":"UNAUTHORIZED","message":"authentication required","detail":[{"Type":"repository","Class":"","Name":"test/someproject","Action":"pull"}]}]}

However, if one tries to do this with an uppercase component, only 404 is returned:

(authorization step done but not shown here)
$ curl -s -H "Authorization: Bearer $TOKEN" -X GET https://docker.uibk.ac.at:443/v2/test/Someproject/tags/list

404 page not found
1

I solve this changing some uppercase words on my Dockerfile like:

FROM Base as Build
RUN npm run Build:prod

to

FROM base as build
RUN npm run build:prod

Another place:

FROM Base as Release
COPY --from=Build /usr/path/here/dist/ ./dist

to

FROM base as Release
COPY --from=build /usr/path/here/dist/ ./dist
0

I had the same error, and for some reason it appears to have been cause by uppercase letters in the Jenkins job that ran the docker run command.

0

This is happening because of the spaces in the current working directory that came from $(pwd) for map volumes. So, I used docker-compose instead.

The docker-compose.yml file.

version: '3'
services:
  react-app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    volumes:
      - /app/node_modules
      - .:/app
0

"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

0

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

0

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

0

I wish the error message would output the problem string. I was getting this due to a weird copy and paste problem of a "docker run" command. A space-like character was being used before the repo and image name.

0

Most of the answers above did not work for my case, so I will document this in case somebody finds it helpful. The first line in the dockerfile FROM node:10 for my case, the word node should not be uppercase i.e FROM NODE:10. I made that change and it worked.

0

In my case DockerFile contained the image name in mixed case instead of lower case.

Earlier line in my DockerFile

FROM CentOs

and when I changed above to FROM centos, it worked smoothly.

0

You need to enter the Name of the Docker-Image and not your File Name :P

$ docker run {your image}

0

Another possible cause of this error is that in your Dockerfile you have mixed capitalization in the syntax declaration itself. For example: # syntax=docker/Dockerfile:1 instead of # syntax=docker/dockerfile:1

0

Similar to other answers, there was a syntax error in my run command. I typed a space instead of an underscore in an environment variable, ENABLE SASLAUTHD vs ENABLE_SASLAUTHD.
Adding the underscore _ fixed the issue.

0

If you are using docker-compose and you get that error, check the name of your services, no upper case letters allowed

enter image description here

0

This error can also appear if you are running a docker run command in a gitlab pipeline which wraps over multiple lines in the pipeline editor. The error is caused when there is a space in one of the parameter names. To find it out, copy over the command to an editor with word wrap switched off, find the offending space and then go back to the same location in the gitlab pipeline editor and keep hitting backspace until the entire parameter name appears together in the same line.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.