How to fix Error response from daemon: invalid reference format in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 483 views

The Docker 'invalid reference format' error means Docker cannot parse your image name. Common causes include uppercase letters, spaces in paths, unset environment variables, or copy-pasted special characters. Fix it by using lowercase names, quoting paths, and verifying your image reference syntax.

Quick fix

Fixes Error response from daemon: invalid reference format

# Wrong
docker pull MyApp:latest
docker run MyImage

# Correct
docker pull myapp:latest
docker run myimage
  1. Check for uppercase letters in image name
  2. Quote paths with spaces in volume mounts
  3. Verify environment variables are set
  4. Check for invisible special characters
docker — error
# Wrong
docker pull MyApp:latest
docker run MyImage
# Correct
docker pull myapp:latest
docker run myimage
Error response from daemon: invalid reference format

What this error means

The "invalid reference format" error occurs when Docker cannot parse the image name you've provided. This is a syntax validation error that happens before Docker even attempts to contact a registry - Docker is telling you that the image reference doesn't follow the required naming rules. A valid Docker image reference must: - Contain only lowercase letters, numbers, hyphens, underscores, and periods - Have at most one colon (to separate the tag) - Not end with special characters like colons or hyphens - Not contain spaces or invisible special characters This error is distinct from "image not found" errors - Docker won't even look for the image until the reference format is valid.

Typical symptoms

  • Docker pull, push, run, or build commands fail immediately
  • Error message appears before Docker attempts to contact the registry
  • Commands work with different image names but fail with specific ones
  • CI/CD pipelines fail at Docker image steps with cryptic errors

Common causes

  1. Image name contains uppercase letters (Docker requires lowercase)
  2. Spaces in volume mount paths when using $(pwd) or similar variables
  3. Unset or empty environment variables in image tags (e.g., image:$VERSION where $VERSION is undefined)
  4. Copy-pasted commands contain invisible special characters (en-dash instead of hyphen)
  5. Missing or malformed image tag (trailing colon like 'ubuntu:' or multiple colons)
  6. Wrong argument order in docker run command (flags after image name)
  7. CRLF line endings in shell scripts on Windows/WSL environments

How to fix "Error response from daemon: invalid reference format"

1Check for uppercase letters in image name

Docker image names must be entirely lowercase. If your image name contains uppercase letters, change them to lowercase.

bash
# Wrong
docker pull MyApp:latest
docker run MyImage

# Correct
docker pull myapp:latest
docker run myimage

This is the most common cause of the invalid reference format error.

2Quote paths with spaces in volume mounts

If you're using $(pwd) or variables in volume mounts, wrap them in quotes to handle spaces properly.

bash
# Wrong - breaks if path contains spaces
docker run -v $(pwd):/app myimage

# Correct - handles spaces in paths
docker run -v "$(pwd)":/app myimage

# Also correct - use full quoting
docker run -v "$(pwd):/app" myimage
3Verify environment variables are set

If you're using environment variables in image names or tags, ensure they're defined and not empty.

bash
# Check if variable is set
echo $IMAGE_TAG

# This will fail if IMAGE_TAG is empty
docker pull myrepo/myimage:$IMAGE_TAG

# Use default value as fallback
docker pull myrepo/myimage:${IMAGE_TAG:-latest}

# Or verify before running
if [ -z "$IMAGE_TAG" ]; then
  echo "IMAGE_TAG is not set"
  exit 1
fi
4Check for invisible special characters

Commands copied from websites, PDFs, or documentation may contain invisible special characters like en-dashes instead of hyphens.

bash
# If you copied a command, try retyping it manually
# Pay special attention to:
# - Hyphens (-)
# - Colons (:)
# - Slashes (/)

# Use hexdump to detect hidden characters
echo "your-command" | hexdump -C

Delete the suspicious characters and retype them manually.

5Fix malformed image tags

Ensure your image reference follows the correct format: name:tag with only one colon.

bash
# Wrong formats
docker pull ubuntu:          # Trailing colon
docker pull ubuntu:18.04:2   # Multiple colons
docker pull ubuntu-          # Trailing hyphen

# Correct formats
docker pull ubuntu           # Uses :latest implicitly
docker pull ubuntu:22.04     # Explicit tag
docker pull myregistry.com/myimage:v1.0.0
6Verify command argument order

In docker run, flags must come before the image name. Anything after the image name is treated as a command to run inside the container.

bash
# Wrong - -d flag after image name
docker run nginx -d

# Correct - flags before image name
docker run -d nginx

# Wrong - -p flag in wrong position
docker run myimage -p 8080:80

# Correct
docker run -p 8080:80 myimage
7Convert CRLF to LF in scripts (Windows/WSL)

If running Docker commands from shell scripts on Windows or WSL, line ending issues can cause this error.

bash
# Check line endings
file yourscript.sh

# Convert CRLF to LF using sed
sed -i 's/\r$//' yourscript.sh

# Or use dos2unix
dos2unix yourscript.sh

In VS Code, you can change line endings by clicking "CRLF" in the status bar and selecting "LF".

Advanced notes

### Registry-specific naming rules

Different registries may have additional naming constraints:

- Docker Hub: Images are username/imagename:tag or official images like nginx:latest
- AWS ECR: Format is aws_account_id.dkr.ecr.region.amazonaws.com/repository:tag
- Google GCR: Format is gcr.io/project-id/image:tag

### Debugging with --help

If you're unsure about argument order, use docker run --help to see the correct syntax:

bash
Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Everything after IMAGE is passed to the container, not to Docker.

### Shell variable expansion

When using variables, be aware of when they're expanded:

bash
# Single quotes prevent expansion (wrong)
docker pull 'myimage:$TAG'

# Double quotes allow expansion (correct)
docker pull "myimage:$TAG"

Frequently asked questions

What does "Error response from daemon: invalid reference format" mean?
The "invalid reference format" error occurs when Docker cannot parse the image name you've provided. This is a syntax validation error that happens before Docker even attempts to contact a registry - Docker is telling you that the image reference doesn't follow the required naming rules. A valid Docker image reference must: - Contain only lowercase letters, numbers, hyphens, underscores, and periods - Have at most one colon (to separate the tag) - Not end with special characters like colons or hyphens - Not contain spaces or invisible special characters This error is distinct from "image not found" errors - Docker won't even look for the image until the reference format is valid.
How do I fix "Error response from daemon: invalid reference format"?
The Docker 'invalid reference format' error means Docker cannot parse your image name. Common causes include uppercase letters, spaces in paths, unset environment variables, or copy-pasted special characters. Fix it by using lowercase names, quoting paths, and verifying your image reference syntax.
What causes "Error response from daemon: invalid reference format"?
Image name contains uppercase letters (Docker requires lowercase) Spaces in volume mount paths when using $(pwd) or similar variables Unset or empty environment variables in image tags (e.g., image:$VERSION where $VERSION is undefined)
Is the "Error response from daemon: invalid reference format" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading