What does docker:invalid_reference_lowercase mean?

Docker rejected the image reference because repository names must be lowercase, so uppercase letters or malformed syntax made it invalid.

How do I prevent docker:invalid_reference_lowercase in CI?

Keep registry namespaces and repository names lowercase across repos, env vars, and CI templates. Validate generated image references in scripts before calling Docker.

invalid reference format: repository name must be lowercase

Fix it fast

Most likely: One of the repository path segments before the optional tag or digest contains uppercase text, for example MyOrg/API:latest instead of myorg/api:latest.

1. Confirm this is your error

Invalid: MyOrg/API:latest
Invalid: ghcr.io/Acme/backend:1.4.2
Valid: myorg/api:latest

2. Check the cause

printf '%s\n' '<image-reference>'
docker pull '<image-reference>'
docker build -t '<image-reference>' .

3. Apply the safe fix

# Lowercase the registry, namespace, and repository path segments.
# Keep the tag or digest intentional.

docker pull myorg/api:latest
docker build -t ghcr.io/acme/backend:1.4.2 .

4. Verify it works

docker pull <lowercase-image-reference>
docker build -t <lowercase-image-reference> .

Don't use unsafe shortcuts

Do not debug registry auth or networking for this error, Docker rejects the reference before contacting a registry.
Do not blindly lowercase the whole string if your tag is intentionally mixed case, lowercase the repository path.
Do not assume CI variables preserve lowercase just because the source repository or organization name is mixed case.

What Is Wrong With the Image Reference

Docker rejected the image reference locally before it tried to contact a registry. This is about the name you passed, not registry availability.

Fix the image reference syntax

Print the final image reference string before running Docker so you can see the exact mixed-case value.

Convert the repository path to lowercase (for example MyOrg/API:latest -> myorg/api:latest).

If a script builds the reference from variables, normalize those variables before concatenating them.

Retry the original docker pull, docker run, or docker build -t command with the lowercase reference.

Why Docker Rejected the Reference

Usually this comes down to one or more repository path segments contain uppercase letters, an environment variable expanded into a mixed-case image name at runtime, or the command copied an image reference from documentation or CI variables without normalizing it.

Re-run the Corrected Image Reference

Run the corrected command and confirm Docker accepts the image reference.

If the value comes from CI variables, print the resolved value in CI and confirm it is lowercase there too.

Check the exact image reference you passed

Echo the final reference string from the shell or CI logs.

Check each repository segment for uppercase letters before the optional :tag or @sha256:... suffix.

How Docker validates the command before it runs

Docker parses image references locally before it makes any registry request. Repository names are restricted to lowercase syntax, so mixed-case references fail immediately.

Prevent It From Coming Back

To prevent this, keep registry namespaces and repository names lowercase across repos, env vars, and CI templates, and validate generated image references in scripts before calling Docker.