Docker "name invalid: invalid reference format" - Uppercase Repo Names

The registry rejected the image name because the repository path contains uppercase letters. Registries require lowercase repository names, and ${{ github.repository }} often carries the original casing.

What this error means

A docker push reaches the registry and is rejected with name invalid: invalid reference format. The image built fine; the registry refuses the name because of capital letters in the namespace or repo.

denied: name invalid: invalid reference format
# tag was: ghcr.io/MyOrg/My-API:1.4.2  (uppercase MyOrg / My-API)

Common causes

Uppercase letters in the repository path

GHCR and most registries require lowercase repository names. A name derived from ${{ github.repository }} keeps the org/repo’s original casing, which can include capitals.

Mixed-case org or image variable interpolated as-is

An image reference built from a branch, org, or repo variable without lowercasing produces an invalid name at push time.

How to fix it

Lowercase the repository before tagging

Normalize the dynamic name to lowercase in the workflow.

- name: Set lowercase image name
  run: echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}/api" >> "$GITHUB_ENV"
- run: docker build -t "$IMAGE:1.4.2" . && docker push "$IMAGE:1.4.2"

Use a metadata action to derive valid tags

docker/metadata-action emits already-lowercased, valid references.

- id: meta
  uses: docker/metadata-action@v5
  with:
    images: ghcr.io/${{ github.repository }}

How to prevent it

• Always lowercase org/repo values before putting them in an image name.
• Use docker/metadata-action to generate compliant tags.
• Keep image references in one place so casing is easy to audit.

Related guides