docker: invalid reference format (repository name must be lowercase)
Docker couldn’t parse the image name — uppercase letters, spaces, an empty variable, or a misplaced option.
invalid reference formatrepository name must be lowercaseinvalid reference format: repository name must be lowercase Meaning
Image references must be lowercase and look like [registry/]name[:tag|@digest]. A common cause is $(pwd) with spaces breaking a -v argument, so part of a path is read as the image name, or an unset variable leaving “myorg/:1.0”.
Common causes
- Uppercase letters in the image name
- Space in a path ($(pwd)) splitting arguments
- Empty variable in the tag (image:${TAG})
- Options placed after the image name
- Smart quotes/dashes pasted from a web page
⚡ Quick fix
- Lowercase the name
- Quote paths: -v "$(pwd)":/app
- Check variables are set (echo "$TAG")
- Put all options before the image name
Detailed fix by platform
Docker
docker run --rm -v "$(pwd)":/app -w /app node:20 npm test
How to diagnose
- Name — Uppercase or odd characters?
- Variables — echo each one
- Order — Options before the image?
🔧 Still not fixed?
Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:
Similar errors
- 1011 Cloudflare Error 1011: Access denied (Hotlinking denied)
- conflict: unable to remove repository reference conflict: unable to remove repository reference (must force) - container is using its referenced image
- docker-compose: command not found docker-compose: command not found / 'compose' is not a docker command
Most viewed in Docker
- docker-credential-desktop error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH
- did not complete successfully failed to solve: process "/bin/sh -c ..." did not complete successfully: exit code: 1
- lookup registry-1.docker.io: no such host dial tcp: lookup registry-1.docker.io: no such host / Temporary failure in name resolution during docker build
Other ways to find it
Where this error sits
Origin: Platform & cloud. Errors that are often confused with or caused by this one (click to open):
🧠 Still stuck? Analyze your error
Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.
💬 What worked for others
No tips yet — did something else fix this for you?
Share what worked for you
Tips are checked by an editor before they appear. Links are removed.
Report a correction or suggest an improvement
Last updated 13 Oct 2026