Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker says invalid reference format for an image name

Errordocker: invalid reference format

Short answer

Docker could not parse the image name it was given. Print the exact string first, because an empty or unquoted variable is the most common source. Then check the rules: repository names are lowercase, and tags use letters, digits, underscore, period and hyphen, at most 128 characters.

  • Applies to Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the command with its variables expanded, so you see the real string Docker received.

    set -x
    docker run --rm "$IMAGE"
  2. 2Match what you see, then jump to its fix

    1. 1repository name must be lowercaseThe image name has uppercase letters or characters that are not allowedFix
    2. 2The printed command shows myapp: with nothing after the colon, or an image of an empty stringA variable in the reference is empty or contains a spaceFix
    3. 3The word Docker complains about is a flag, a path or a quoted commandOptions or the image are in the wrong orderFix

What does the error look like?

  • docker: invalid reference format
  • invalid reference format: repository name must be lowercase
  • invalid reference format

Cause 1 of 3

The image name has uppercase letters or characters that are not allowed

1Check

Each path part of a repository name may use lowercase letters and digits, joined by single separators such as period, underscore or hyphen. Tags allow word characters, period and hyphen, and are at most 128 characters long.

echo "$IMAGE"

2Fix

Lowercase the name and remove any space, slash at the wrong place or odd characters. A Git branch like feature/x cannot be a tag as it is, so replace the slash.

TAG=$(echo "$GIT_BRANCH" | tr '[:upper:]/' '[:lower:]-')
docker build -t myapp:"$TAG" .

3Verify

The build or run starts.

docker image ls myapp

Confirmed by github.com

Did this fix it?

Cause 2 of 3

A variable in the reference is empty or contains a space

1Check

An unset shell or CI variable leaves a trailing colon or an empty name, and both are invalid.

set -u
echo "image=$IMAGE tag=$TAG"

2Fix

Give the variable a default and quote it, so a missing value falls back to a valid tag.

docker build -t "myapp:${TAG:-latest}" .

3Verify

The tag is created.

docker image ls myapp

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

Options or the image are in the wrong order

1Check

In docker run, options come before the image name, and the command comes after it. A pasted line with a smart quote or a dash that is not a plain hyphen also breaks parsing.

docker run --help | head -n 5

2Fix

Put the options first, then the image, then the command, and retype the dashes by hand if the line was copied from a web page.

docker run --rm -p 8080:80 nginx:latest

3Verify

The container starts.

docker ps

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Lowercase image names in your build scripts, and sanitise branch names before using them as tags.
  • Use ${VAR:?message} in scripts so an empty variable stops the script with a clear message.
  • Quote variables that hold image references.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.