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

```text
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.