invalid reference format 🐳 Docker

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.

Seen on: Docker

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

  1. Lowercase the name
  2. Quote paths: -v "$(pwd)":/app
  3. Check variables are set (echo "$TAG")
  4. Put all options before the image name

Detailed fix by platform

Docker

  1. docker run --rm -v "$(pwd)":/app -w /app node:20 npm test

How to diagnose

  1. Name — Uppercase or odd characters?
  2. Variables — echo each one
  3. 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:

🧠 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.