Docker "invalid reference format": What It Means and How to Fix It
Docker invalid reference format means the image name you passed isn't valid. The usual culprits: uppercase, spaces in paths, empty tags and stray characters.
Docker's "invalid reference format" means the string Docker tried to read as an image name (the "reference") breaks the naming rules. The usual causes are uppercase letters, an empty variable that leaves a tag like myapp:, a path with spaces that splits your command so part of it lands where the image name should be, or a stray character pasted in from a web page. The fix is to find the exact string Docker treated as the image name, which is often not the one you think.
Checked against the distribution/reference source (the parser Docker uses), the Docker CLI and Compose source, and the docker image tag docs in November 2026.
The error comes in a few shapes:
docker: invalid reference format
Run 'docker run --help' for more information
docker: invalid reference format: repository name (library/MyApp) must be lowercase
ERROR: invalid tag "MyApp": repository name must be lowercase
The first two come from docker run (older Docker versions print See 'docker run --help'. underneath instead). The third is what docker build -t prints. They're all the same check failing.
What a valid image reference looks like
An image reference has up to four parts:
registry.example.com:5000/team/myapp:1.4.2
└──── registry ────────┘ └─ path ─┘ └tag┘
The rules, taken from the regular expressions in the distribution/reference package:
| Part | Rules |
|---|---|
| Registry (optional) | A hostname, optionally with :port. Without one, Docker uses Docker Hub and adds library/ for official images. |
| Repository path | Lowercase letters and digits, separated by ., _, __ or one or more -. Path parts separated by /. The whole name can be at most 255 characters. |
| Tag (optional) | After a :. Letters (upper or lower case), digits, _, . and -, up to 128 characters, and it can't start with . or -. |
| Digest (optional) | After an @, like @sha256:.... |
So myapp, myapp:latest, ghcr.io/acme/web:2026-11-18 and localhost:5000/api:v2 are all fine. MyApp, myapp:, my app and myapp:-dev are not.
Cause 1: uppercase letters in the repository name
docker build -t MyApp .
docker run MyApp
Repository names must be lowercase. This catches people who name images after their project folder or their GitHub repo. The fix is to lowercase it:
docker build -t myapp .
Tags may contain uppercase (myapp:RC1 is valid), so if the error mentions "must be lowercase", look at the part before the colon.
Cause 2: a path with spaces splits your command
This is the most confusing one, because the image name in your command looks fine:
docker run -v $(pwd):/app node:22 npm test
If your current directory is /Users/sam/My Projects/api, the shell expands $(pwd) and then splits the result on the space. Docker receives -v /Users/sam/My as the volume, and Projects/api:/app as the next argument, which it treats as the image name. Projects/api:/app isn't a valid reference (the :/app part can't be a tag), so it fails.
The fix is to quote the expansion:
docker run -v "$(pwd)":/app node:22 npm test
On Windows, the same problem shows up with %cd% in cmd and ${PWD} in PowerShell when the path contains spaces. Wrap the whole -v value in double quotes: -v "${PWD}:/app". (Docker Volumes vs Bind Mounts explains what that flag is mounting.)
Quickest way to see what the shell actually passes: put echo in front of the command.
echo docker run -v $(pwd):/app node:22 npm test
Cause 3: an empty variable leaves a dangling colon
Scripts and CI pipelines often build the tag from a variable:
docker build -t myapp:$VERSION .
If VERSION is unset or empty, Docker sees myapp:, a colon with no tag after it, and rejects it. The same thing happens with $REGISTRY/myapp when REGISTRY is empty: the reference becomes /myapp, which also fails.
Fixes:
- Print the variable before the command (
echo "VERSION=$VERSION") to confirm it's set in that shell or CI step. - Give it a default:
docker build -t "myapp:${VERSION:-dev}" . - In CI, make sure the variable is defined in the job that runs the build, not just in an earlier one. (Why Is My Environment Variable Undefined? covers the common ways variables go missing.)
A related trap: a .env file saved with Windows line endings can leave an invisible carriage return at the end of the value, so the tag becomes 1.4.2\r. That's not a valid tag character. Convert the file to LF line endings.
Cause 4: Docker Compose image: values
Compose interpolates variables into image: the same way:
services:
web:
image: ${REGISTRY}/web:${TAG}
If TAG isn't set, Compose prints a warning and carries on with an empty string:
WARN[0000] The "TAG" variable is not set. Defaulting to a blank string.
The resulting /web: is then rejected as an invalid reference. Scroll up for that warning; it names the variable. Either set it in .env next to the compose file, or make Compose stop early with a clear message using the :? form:
image: ${REGISTRY:?set REGISTRY}/web:${TAG:-latest}
Cause 5: stray characters and argument order
Things that turn a valid-looking command into a bad reference:
- Copied dashes. Blogs and chat apps sometimes turn
--rminto—rm(an em dash) or-pinto–p(an en dash). Docker doesn't recognise it as a flag and treats it as the image name. Retype the dashes by hand. - Spaces in the wrong place.
-p 8080 :80passes:80as a separate argument, and-e KEY = valuesplits into three. Whatever lands first after the flags is read as the image. - Smart quotes.
"myapp"with curly quotes from a document is not quoted at all to the shell; the quote characters become part of the name. https://in front of the registry. References areghcr.io/org/app, nothttps://ghcr.io/org/app.
Docker reads everything up to the image name as options, so the image has to come after all the flags, and anything after the image is passed to the container as its command:
docker run [options] IMAGE [command] [args]
Quick checklist
- Put
echoin front of the command to see the real arguments after the shell expands variables and paths. - Find the argument right after the last flag. That's what Docker is parsing.
- Lowercase the repository part; keep the tag after a single
:. - Quote anything containing
$(pwd),${PWD}or a variable. - Check for empty variables, Windows line endings and pasted dashes or quotes.
- In Compose, look for "variable is not set" warnings above the error.
For the everyday commands around images and tags, see the Docker Commands Cheat Sheet.
EasySpawn runs your projects on a persistent Linux server with Claude Code working in the same shell, so build scripts run in a consistent environment with paths and variables you can inspect, rather than across a mix of laptops and CI runners. See how it works or join the waitlist.
Related: Docker Commands Cheat Sheet: The 40 You'll Actually Use · Docker Image vs Container: What's the Difference? · Docker Volumes vs Bind Mounts: Where Your Data Actually Lives · Why Is My Environment Variable Undefined? (Vite, Next.js, Node)
Keep reading
Docker Exit Code 137: Why Your Container Was Killed and How to Fix It
Docker exit code 137 means the container got SIGKILL, usually from the out-of-memory killer. How to confirm OOMKilled, find the limit you hit, and fix it.
Docker "error getting credentials": What It Means and How to Fix It
Docker error getting credentials means config.json points at a credential helper that is missing or failing. Fixes for Mac, Windows, WSL and Linux servers.