# Docker "invalid reference format" in CI

> Fix Docker "invalid reference format" in CI - an image name/tag with uppercase, illegal characters, an empty variable, or a malformed registry/tag breaks the reference.

Source: https://latchkey.dev/learn/docker/docker-invalid-reference-format-in-ci  
Updated: 2026-06-26

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.

## Diagnose it: separate auth from naming from rate limits

Registry errors look alike and have unrelated causes. Work out which of the three you have before changing credentials, because a malformed image reference produces an error that reads like an authentication failure.

```Terminal
# 1. is the reference even valid? (lowercase, no spaces, valid tag)
docker image inspect "$IMAGE" 2>&1 | head -2

# 2. are you authenticated to the right registry?
cat ~/.docker/config.json | grep -o '"[^"]*\.[^"]*"' | head

# 3. are you rate limited? (Docker Hub anonymous pulls)
curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimit-preview/test:pull" \
  | grep -o '"token"' >/dev/null && echo "token ok"
```

> Docker Hub rate-limits anonymous pulls by IP, and CI runners share IPs. A pull that works on your laptop and fails in CI with no config change is usually this, not credentials.

## Authenticate in the job, not in the image

```.github/workflows/ci.yml
- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

# GHCR needs this on the job or the push is rejected as unauthorised
permissions:
  contents: read
  packages: write
```

## FAQ

### What causes Docker "invalid reference format" in CI?

There are 3 common causes: uppercase or illegal characters in the name, an empty interpolated variable, and stray or doubled separators. Repository names must be lowercase and use a limited character set.

### How do I fix Docker "invalid reference format" in CI?

There are 2 fixes depending on which cause you have: use a lowercase, fully-formed reference and default tag variables so they are never empty. Work through them in order, since the first is the most common.

### What does Docker "invalid reference format" in CI actually mean?

A docker build -t, docker tag, docker push, or docker pull fails immediately with invalid reference format.

### How do I stop Docker "invalid reference format" in CI happening again?

Keep repository names lowercase and within the allowed character set. The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt