EC
invalid reference format
DockerERRORBuildHIGH confidence

Image name contains invalid characters or format

What this means

This error means the name you are trying to give an image or tag is invalid. Image names have strict formatting rules: they must be lowercase, and can contain letters, numbers, hyphens, underscores, and periods, but cannot start with a special character.

Why it happens
  1. 1Using uppercase letters in the image name (e.g., 'my-registry/My-App').
  2. 2Including invalid special characters like '!' or '
    #x27; in the name or tag.
  3. 3The image name starts or ends with a separator like a period, hyphen, or underscore.
  4. 4The tag name is too long (max 128 characters).
How to reproduce

Trying to tag an image with a name containing uppercase letters.

trigger — this will error
trigger — this will error
docker tag my-app:latest my-registry/MyFancyApp:1.0

expected output

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

Fix 1

Use Lowercase for Image Names

WHEN The error message explicitly says 'repository name must be lowercase'.

Use Lowercase for Image Names
# Corrected command
docker tag my-app:latest my-registry/myfancyapp:1.0

Why this works

Adheres to the Docker standard for image repository naming.

Fix 2

Remove Invalid Characters

WHEN The name contains special characters other than '.', '_', or '-'.

Remove Invalid Characters
# Original: myapp:version_!
# Corrected command
docker tag my-app:latest my-app:version-1

Why this works

Ensures the image name and tag only contain allowed characters.

What not to do

✕ Try to force the invalid name.

The naming restrictions are enforced by Docker and container registries. There is no way to bypass them. The only solution is to use a valid name.

Sources

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Docker errors