ProjectStack
docker

Error parsing reference: invalid reference format

The image name or tag you provided contains invalid characters or doesn't follow Docker's image naming format. Docker image references follow strict rules: lowercase letters, digits, dots, dashes, and underscores — no spaces, uppercase letters in most positions, or special characters.

Common causes

  • Uppercase letters in the image name — Docker Hub names must be lowercase
  • Spaces in the image name or tag, often from a copy-paste with a trailing newline
  • Special characters like @ or ! in the tag
  • A colon in the wrong place or multiple colons in the reference

How to fix it

  1. Convert the image name to lowercase: docker build -t myapp:v1 . (not MyApp:v1)
  2. Trim whitespace and hidden characters: pipe through tr -d '\n' or echo the value to inspect it
  3. Use only letters, digits, dots (.), dashes (-), and underscores (_) in image names and tags
  4. For SHA digest references, use the @ format correctly: image@sha256:HASH

Example

$ docker pull My Image:latest Error response from daemon: invalid reference format

Image name has a space and uppercase letters, neither of which are valid in Docker image references

Related Docker Errors

Cannot connect to Docker daemonPermission denied connecting to Docker socketDocker daemon not running on this hostImage not found or pull access deniedImage manifest not found (tag doesn't exist)

Browse more errors

The Developer Hub covers 150+ errors across Git, npm, Node.js, Python, TypeScript, and Docker — with plain-English explanations and fix steps.