docker says invalid reference format for an image name
docker: invalid reference formatShort 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.
Fix it fast
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"2Match what you see, then jump to its fix
- 1
repository name must be lowercaseThe image name has uppercase letters or characters that are not allowedFix - 2
The 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
The word Docker complains about is a flag, a path or a quoted commandOptions or the image are in the wrong orderFix
- 1
What does the error look like?
docker: invalid reference formatinvalid reference format: repository name must be lowercaseinvalid 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 myappConfirmed by github.com
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 myappConfirmed by docs.docker.com
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 52Fix
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:latest3Verify
The container starts.
docker psConfirmed by docs.docker.com
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
Servers
docker push is denied: requested access to the resource is denied
push access denied, repository does not exist or may require authorization
The registry refused the push.
3 causes, each with a fixServers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 causes, each with a fix