How to fix Error response from daemon: invalid reference format: repository name must be lowercase in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 328 views

The 'repository name must be lowercase' error occurs when you use uppercase characters in a Docker image name, tag, or related paths. Docker image references must be all lowercase. The fix is simple: convert all uppercase letters to lowercase in your image names and related configurations.

Quick fix

Fixes Error response from daemon: invalid reference format: repository name must be lowercase

# Wrong - uppercase letters
docker build -t MyApp:latest .
docker pull NginX:alpine
docker run -it Ubuntu:22.04

# Correct - all lowercase
docker build -t myapp:latest .
docker pull nginx:alpine
docker run -it ubuntu:22.04

Convert the image name to lowercase
Fix uppercase in docker-compose.yml
Fix uppercase in Dockerfile multi-stage builds
Check and fix environment variables

docker — error

$# Wrong - uppercase letters
docker build -t MyApp:latest .
docker pull NginX:alpine
docker run -it Ubuntu:22.04
# Correct - all lowercase
docker build -t myapp:latest .
docker pull nginx:alpine
docker run -it ubuntu:22.04
Error response from daemon: invalid reference format: repository name must be lowercase

What this error means

This error indicates that Docker's image reference parser encountered an uppercase letter where only lowercase is allowed. Docker follows strict naming conventions for image references based on DNS naming rules, which require all repository names to be lowercase. When you run commands like `docker build`, `docker pull`, or `docker run`, Docker parses the image reference (e.g., `myregistry.com/myrepo/myimage:tag`). If any part of the repository name contains uppercase letters, Docker rejects it with this error. The restriction exists because: 1. **DNS compatibility** - Registry hostnames must follow DNS rules, which are case-insensitive but conventionally lowercase 2. **Consistency** - Having a single canonical form prevents confusion between `MyImage` and `myimage` 3. **URL safety** - Image references are used in URLs, where case sensitivity can vary

Typical symptoms

docker build fails with 'invalid reference format' before building any layers
docker pull fails immediately without contacting the registry
docker run fails with the error before attempting to start the container
docker-compose up fails when image names contain uppercase letters
CI/CD pipelines fail at image build or push steps
The error appears despite the image name looking correct at first glance

Common causes

Image name contains uppercase letters (e.g., 'MyApp' instead of 'myapp')
Docker Compose service name has uppercase letters and is used to auto-generate image names
Dockerfile multi-stage build uses uppercase in AS clause (e.g., 'FROM node AS BUILD')
Environment variable used in image name is empty or contains uppercase (e.g., docker build -t $PROJECT_NAME)
Working directory path contains uppercase letters when used with $(pwd) in volume mounts
Path contains spaces that break the command parsing, making Docker misinterpret the image name
Registry hostname or namespace contains uppercase letters
Tag name contains uppercase letters (less common but still invalid)

How to fix "Error response from daemon: invalid reference format: repository name must be lowercase"

1Convert the image name to lowercase

The most common fix is simply changing your image name to lowercase:

bash

# Wrong - uppercase letters
docker build -t MyApp:latest .
docker pull NginX:alpine
docker run -it Ubuntu:22.04

# Correct - all lowercase
docker build -t myapp:latest .
docker pull nginx:alpine
docker run -it ubuntu:22.04

Docker image names must only contain:
- Lowercase letters (a-z)
- Digits (0-9)
- Separators: periods (.), underscores (_), and hyphens (-)

2Fix uppercase in docker-compose.yml

Docker Compose auto-generates image names from the service name. If your service name has uppercase letters, the generated image name will too:

yaml

# Wrong - uppercase in service name
services:
  MyService:
    build: .

# Correct - lowercase service name
services:
  myservice:
    build: .

Or explicitly set a lowercase image name:

yaml

services:
  MyService:
    build: .
    image: myservice:latest  # Explicit lowercase image name

3Fix uppercase in Dockerfile multi-stage builds

When using multi-stage builds, the AS clause must also be lowercase:

dockerfile

# Wrong - uppercase stage name
FROM node:20 AS BUILD
RUN npm install
FROM node:20-slim AS RUNTIME
COPY --from=BUILD /app /app

# Correct - lowercase stage names
FROM node:20 AS build
RUN npm install
FROM node:20-slim AS runtime
COPY --from=build /app /app

While some Docker versions may accept uppercase stage names, lowercase is the safe and recommended approach.

4Check and fix environment variables

If you use environment variables in image names, ensure they're set and lowercase:

bash

# Check if variable is set
echo $PROJECT_NAME

# If empty, the command becomes invalid
docker build -t :latest .  # This causes the error!

# Fix: Ensure variable is set and lowercase
export PROJECT_NAME=myproject
docker build -t $PROJECT_NAME:latest .

# Or use lowercase transformation in bash
docker build -t ${PROJECT_NAME,,}:latest .  # Bash 4+ lowercase

In CI/CD pipelines, verify environment variables are properly passed to Docker commands.

5Quote paths with spaces in volume mounts

Spaces in paths can cause Docker to misparse the command:

bash

# Wrong - unquoted path with spaces breaks parsing
docker run -v $(pwd):/app myimage  # If pwd = "/home/user/My Project"

# Correct - quote the entire volume argument
docker run -v "$(pwd):/app" myimage

# Or use $PWD with quotes
docker run -v "$PWD:/app" myimage

In PowerShell, use curly braces:

powershell

# PowerShell syntax
docker run -v "${pwd}:/app" myimage

6Handle uppercase in working directory paths

Some Docker operations may incorporate the working directory name. If your directory has uppercase letters, consider renaming it:

bash

# Check current directory
pwd  # Output: /home/user/MyProject

# Option 1: Rename the directory to lowercase
cd ..
mv MyProject myproject
cd myproject

# Option 2: Explicitly set a lowercase image name
docker build -t myproject:latest .  # Don't rely on auto-naming

This is especially relevant when Docker Compose infers project names from directory names.

7Verify registry and namespace are lowercase

The full image reference includes registry and namespace, which must all be lowercase:

bash

# Wrong - uppercase in registry or namespace
docker push MyRegistry.com/MyOrg/myimage:latest
docker pull GHCR.io/MyUser/myapp:v1

# Correct - everything lowercase
docker push myregistry.com/myorg/myimage:latest
docker pull ghcr.io/myuser/myapp:v1

Check your Docker login and registry configuration:

bash

# View current login credentials
cat ~/.docker/config.json | jq '.auths | keys'

Advanced notes

### Why Lowercase Only?

Docker's image reference format follows the OCI (Open Container Initiative) distribution specification, which mandates lowercase repository names. This ensures:

1. Cross-platform compatibility - File systems handle case differently (Linux is case-sensitive, Windows/macOS often aren't)
2. URL safety - Registry URLs must work consistently across HTTP clients
3. DNS compliance - Registry hostnames follow DNS naming rules

### Automating Lowercase Conversion

In CI/CD pipelines, automatically convert to lowercase:

bash

# Bash 4+
IMAGE_NAME=${REPO_NAME,,}

# POSIX-compatible
IMAGE_NAME=$(echo "$REPO_NAME" | tr '[:upper:]' '[:lower:]')

# In GitHub Actions
- name: Build image
  run: |
    IMAGE_NAME=$(echo "${{ github.repository }}" | tr '[:upper:]' '[:lower:]')
    docker build -t ghcr.io/$IMAGE_NAME:latest .

### Regex for Valid Image Names

A valid Docker image name must match:

bash

^[a-z0-9]+([._-][a-z0-9]+)*(/[a-z0-9]+([._-][a-z0-9]+)*)*$

The full reference (including registry and tag):

bash

[registry/][namespace/]repository[:tag|@digest]

### Common Mistakes in Different Environments

GitHub Actions:

yaml

# Wrong - repository may have uppercase
docker build -t ghcr.io/${{ github.repository }}:latest

# Correct - force lowercase
docker build -t ghcr.io/$(echo ${{ github.repository }} | tr A-Z a-z):latest

GitLab CI:

yaml

# Use CI_PROJECT_PATH_SLUG which is already lowercase
docker build -t $CI_REGISTRY_IMAGE/$CI_PROJECT_PATH_SLUG:$CI_COMMIT_REF_SLUG

Jenkins:

groovy

def imageName = env.JOB_NAME.toLowerCase()
sh "docker build -t ${imageName}:${env.BUILD_NUMBER} ."

Frequently asked questions

What does "Error response from daemon: invalid reference format: repository name" mean?: This error indicates that Docker's image reference parser encountered an uppercase letter where only lowercase is allowed. Docker follows strict naming conventions for image references based on DNS naming rules, which require all repository names to be lowercase. com/myrepo/myimage:tag).
How do I fix "Error response from daemon: invalid reference format: repository name"?: The 'repository name must be lowercase' error occurs when you use uppercase characters in a Docker image name, tag, or related paths. Docker image references must be all lowercase. The fix is simple: convert all uppercase letters to lowercase in your image names and related configurations.
What causes "Error response from daemon: invalid reference format: repository name"?: Image name contains uppercase letters (e.g., 'MyApp' instead of 'myapp') Docker Compose service name has uppercase letters and is used to auto-generate image names Dockerfile multi-stage build uses uppercase in AS clause (e.g., 'FROM node AS BUILD')
Is the "Error response from daemon: invalid reference format: repository name" error serious?: It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Docker Official Documentation
💬
Stack Overflow - Repository name must be lowercase(Stack Overflow)
💬
Stack Overflow - Lowercase images names in Docker(Stack Overflow)
🐙
GitHub - Uppercase letters in service names result in errors(GitHub)
📖
LabEx - Troubleshooting Invalid Reference Format Error(Official Docs)
📝
Bobcares - Docker Error Invalid Reference Format
📝
100 Common Docker Errors & Solutions

How to fix Error response from daemon: invalid reference format: repository name must be lowercase in Docker

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "Error response from daemon: invalid reference format: repository name must be lowercase"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading