docker: invalid reference format

TL;DR: Your image name or tag breaks the naming rules. Use lowercase, no spaces, and the form [registry/][namespace/]name[:tag]; quote the whole thing if your shell might split it. The single most common cause is an uppercase letter or a stray space in -t.

The error

docker: invalid reference format.

Fix it

1. Inspect the name you passed to -t/--tag or the image argument.

2. Apply the rules: all lowercase, allowed chars are a-z 0-9 _ . - plus / separators, tag after : max 128 chars: docker build -t myregistry/myapp:1.2.3 . Expected: build starts.

3. Common fixes:

   • MyApp becomes myapp
   • my app becomes my-app (or quote it, but renaming is better)
   • registry:5000/image needs the port attached to a hostname: myhost:5000/image is valid only if myhost contains a . or : and is lowercase
4. Re-run.

When this applies

• docker build -t, docker tag, docker run, docker push rejecting the name
• CI variables interpolated into tags (branch names with / or uppercase)

When this does NOT apply

• "repository name must be lowercase" (that is the specific variant; same family, clearer message)
• Pull failures with a valid name (manifest/auth problems instead)

Versions

All Docker versions; the reference grammar has been stable for years.

Why it happens

Image references are parsed by a strict grammar before anything touches the network. Uppercase, spaces, leading dashes, or a : in the wrong place all fail parsing, and the CLI reports the generic message without saying which character offended.

Edge cases

• A tag like :latest with a trailing space (from shell variables) fails; trim it.
• Windows paths accidentally used as tags (-t C:\img) fail; that is a different mistake wearing this error.
• Registry hostnames must be lowercase; a single label without dots is treated as a Docker Hub namespace, not a registry host.

Asked: how to fix docker: invalid reference format. Verified answer: Fixes 'docker: invalid reference format' when tagging or naming images. Use when docker build -t, docker tag, or docker run reject the image name, usually from uppercase letters, spaces, or a malformed registry prefix. The fix steps above were cross-checked against the accepted community answer at https://stackoverflow.com/questions/45682010/docker-invalid-reference-format (so:45682010), which confirms the same resolution.