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

DockerBEGINNERLOW

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 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

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'

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

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

Related errors

Official resources & further reading