🚨 Docker Error Guide: 'invalid reference format' — Malformed Image Name or Tag

Overview

Docker parses image references into a strict [registry[:port]/]repository[:tag][@digest] grammar. Any character or structure that does not fit — uppercase in the repo name, a stray space, a bad tag, or an argument Docker mistook for an image — produces:

docker: invalid reference format.
See 'docker run --help'.

A common variant when a lowercase rule is violated:

invalid reference format: repository name must be lowercase

Symptoms

• docker run, docker build -t, docker tag, or docker pull fails instantly before any network call.
• The same command works after you fix capitalization or remove a space.
• A docker build -t fails when the tag contains an illegal character.
• A docker run with an unquoted flag value is misparsed as the image name.

Common Root Causes

• Uppercase in the repository name — MyApp is invalid; repositories must be lowercase.
• A stray space in the reference — registry.example.com/ myapp:1.4.2 or a space before the tag.
• Illegal tag characters — tags allow [A-Za-z0-9_.-] up to 128 chars; a / or space in the tag breaks parsing.
• Missing image argument — a misplaced docker run -it -v $PWD:/data where the volume path swallowed the image name.
• Unquoted variable that expanded empty or with spaces — docker run $IMAGE where $IMAGE is unset or contains whitespace.
• Registry host with a bad port — registry.example.com:/myapp (empty port) is malformed.

Diagnostic Workflow

Print the exact reference your shell is passing (catch empty or spaced variables):

echo "[$IMAGE]"
set -x; docker run "$IMAGE"; set +x

Validate the pieces of the reference — repo must be lowercase, tag must be legal:

# repository lowercase check
echo "registry.example.com/myapp:1.4.2" | grep -E '^[a-z0-9./_-]+(:[A-Za-z0-9_.-]+)?$'

Confirm what images actually exist locally so you tag/run the right name:

docker images
docker inspect --format '{{index .RepoTags 0}}' <image_id>

Re-run the failing command with the reference explicitly quoted:

docker run "registry.example.com/myapp:1.4.2"

Example Root Cause Analysis

A CI job failed at docker build -t $CI_REGISTRY/$CI_PROJECT:$TAG . with invalid reference format. Adding echo "[$CI_PROJECT]" to the pipeline printed:

[Group/MyApp]

The project slug contained an uppercase segment and a slash from the group path, so the resulting reference registry.example.com/Group/MyApp:build-1 violated the lowercase-repository rule. Docker rejected it before contacting the registry.

The fix normalized the name to lowercase in the pipeline:

REPO=$(echo "$CI_REGISTRY/$CI_PROJECT" | tr '[:upper:]' '[:lower:]')
docker build -t "$REPO:$TAG" .

With the repository lowercased, the reference parsed and the build proceeded. The general rule: when a reference comes from a variable, lowercase it and quote it.

Prevention Best Practices

• Keep repository names entirely lowercase; normalize dynamic names with tr '[:upper:]' '[:lower:]'.
• Always double-quote image references built from shell variables so empty or spaced values fail loudly, not silently.
• Restrict tags to [A-Za-z0-9_.-] and keep them under 128 characters — no slashes or spaces.
• Put the image name last and unambiguous in docker run, after all flags and their values.
• Validate Dockerfiles and image tags in CI with the free Dockerfile validator.

Quick Command Reference

echo "[$IMAGE]"                                   # reveal empty/spaced vars
docker images                                     # confirm real image names
REPO=$(echo "$RAW" | tr '[:upper:]' '[:lower:]')  # normalize case
docker build -t "$REPO:1.4.2" .                   # quoted, lowercase tag
docker run "registry.example.com/myapp:1.4.2"     # quoted reference

Conclusion

invalid reference format is a parse error, not a registry error: the image name, tag, or an argument does not match Docker’s reference grammar. The usual culprits are uppercase repository names, stray spaces, illegal tag characters, or unquoted variables. Echo the value, lowercase and quote dynamic names, and keep the image argument last. Validating tags in CI prevents these from ever reaching a build. For more Docker guidance, see the Docker guides.