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.
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.
Docker image names must be entirely lowercase. If your image name contains uppercase letters, change them to lowercase.
# Wrong
docker pull MyApp:latest
docker run MyImage
# Correct
docker pull myapp:latest
docker run myimageThis is the most common cause of the invalid reference format error.
If you're using $(pwd) or variables in volume mounts, wrap them in quotes to handle spaces properly.
# 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" myimageIf you're using environment variables in image names or tags, ensure they're defined and not empty.
# 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
fiCommands copied from websites, PDFs, or documentation may contain invisible special characters like en-dashes instead of hyphens.
# 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 -CDelete the suspicious characters and retype them manually.
Ensure your image reference follows the correct format: name:tag with only one colon.
# 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.0In docker run, flags must come before the image name. Anything after the image name is treated as a command to run inside the container.
# 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 myimageIf running Docker commands from shell scripts on Windows or WSL, line ending issues can cause this error.
# Check line endings
file yourscript.sh
# Convert CRLF to LF using sed
sed -i 's/\r$//' yourscript.sh
# Or use dos2unix
dos2unix yourscript.shIn VS Code, you can change line endings by clicking "CRLF" in the status bar and selecting "LF".
### 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:
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:
# Single quotes prevent expansion (wrong)
docker pull 'myimage:$TAG'
# Double quotes allow expansion (correct)
docker pull "myimage:$TAG"dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec