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.

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

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