Code Beautifier
docker: invalid reference format

Fix "docker: invalid reference format"

Docker could not parse the image name: an uppercase letter, a stray flag after the image, a bad tag, or a variable that expanded to nothing. The fixes.

Written by · Updated

Input that triggers it

docker run -d --name web -p 80:80 Nginx:1.27
Open Docker Run to Compose on its own page
Options
shell
compose.yamlyaml
Draft saved locally.

What the error means

Every docker run, docker pull, and FROM line names an image by a reference: [registry/][namespace/]repository[:tag|@digest]. Docker parses that reference strictly. docker: invalid reference format means the text it took to be the image name does not fit the grammar, and the variant invalid reference format: repository name must be lowercase tells you which rule failed most often.

In the example, the image is written Nginx:1.27. Repository names must be lowercase, so the reference is rejected before Docker even contacts a registry.

Why it happens

  • An uppercase letter in the repository name. Nginx, MyApp, Ubuntu. Tags may contain uppercase; repository names may not.
  • A flag placed after the image. In docker run nginx -p 80:80, everything after nginx is the command to run inside the container, not options. Docker does not report this as a reference error, but the closely related docker run -p 80:80 -d nginx --name web leaves --name web as the command — and a shell that quoted or split things unexpectedly can put a flag where the image should be.
  • A shell variable that expanded to nothing. docker run $IMAGE with IMAGE unset makes the next argument the image name; if that argument was a flag or a path, it fails this check.
  • A malformed tag or digest: two colons, a space, a trailing colon, or @sha256: with the wrong length.
  • A path where an image was expected, such as docker run ./app — build it first, then run the resulting image.
  • A Windows path or a URL pasted in place of the reference.

How to fix it

  1. Paste the command into the converter above. It tokenizes the command the way a shell does and reports an invalid image reference before generating anything; a valid command becomes a Compose service with the image in its image: line.
  2. Lowercase the repository name. nginx:1.27, not Nginx:1.27. Rename the image if it is yours (docker tag MyApp myapp).
  3. Move every option before the image name. The image is the first non-flag argument; everything after it is the container's command.
  4. Print the exact command that runs (set -x in a shell script) when variables are involved, and confirm each one is set.

The corrected example:

docker run -d --name web -p 80:80 nginx:1.27

If it still fails

  • FROM Nginx in a Dockerfile fails the same way at build time; Dockerfile Formatter flags it.
  • A registry hostname may contain uppercase (it is a DNS name) and a port: registry.example.com:5000/team/app:1.0 is valid. Only the path after the host must be lowercase.
  • If the reference is correct and the message persists, look for an invisible character pasted in from a document; the grammar rejects anything outside [a-z0-9._-/] in the repository.

Related errors