Docker "invalid reference format" in CI

Docker rejected an image reference. invalid reference format means the name/tag is malformed - uppercase in the repository part, illegal characters, an empty interpolated variable, or a stray colon/slash.

What this error means

A docker build -t, docker tag, docker push, or docker pull fails immediately with invalid reference format. The reference string is bad before any registry is contacted.

docker

docker: invalid reference format
# e.g. docker build -t MyOrg/API:1.4.2 .   (uppercase not allowed in repo name)
# or an empty var: docker build -t ghcr.io/myorg/api: .

Common causes

Uppercase or illegal characters in the name

Repository names must be lowercase and use a limited character set. Uppercase letters or illegal characters make the reference invalid.

An empty interpolated variable

A tag built from ${VERSION} where the variable is unset collapses to image: or a missing component, which is malformed.

Stray or doubled separators

An extra colon, a trailing slash, or a double tag produces a reference Docker cannot parse.

How to fix it

Use a lowercase, fully-formed reference

Lowercase the repository and ensure every component is present.

Terminal

docker build -t ghcr.io/myorg/api:1.4.2 .
# lowercase a dynamic name:
docker build -t "ghcr.io/$(echo "$ORG" | tr '[:upper:]' '[:lower:]')/api:1.4.2" .

Default tag variables so they are never empty

Give the tag a fallback so an unset variable does not break the reference.