Fix "docker: invalid reference format"

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.