What This Error Means
Docker rejected the image name because the reference format is invalid, commonly due to uppercase letters, bad tagging, or malformed syntax.
How to Fix It
Print the final image reference string before running Docker, especially if a script or CI template builds it for you.
Validate the shape:<registry>/<namespace>/<repo>:<tag> where the registry and tag are optional but the repository path cannot be empty.
Lowercase the repository and name segments and remove spaces or duplicate separators.
If you use environment variables, make sure none of them expand to an empty value in the middle of the reference.
Retry the original Docker command after correcting the reference.
Why It Happens
The repository name contains uppercase characters.
The reference is missing a required segment, contains spaces, or ends with an empty tag or digest separator.
Variable interpolation produced malformed text such as double slashes, an empty repository, or a trailing colon.
How to Verify
Run the same command with the corrected reference.
Confirm docker pull or docker run accepts the reference.
Manual reference checks
Echo the exact reference string and inspect it character by character.
Look for uppercase letters, spaces, empty segments, double slashes, or a trailing : / @.
If the reference comes from Docker Compose or CI env vars, inspect the fully expanded value rather than the template.
Examples
Invalid: MyOrg/App:latest
Invalid: ghcr.io/acme//api:latest
Invalid: myrepo:
Valid: ghcr.io/acme/api:1.4.2
Valid: ubuntu:24.04How Docker parses image references
Docker parses image references locally before it contacts a registry.
Because parsing happens first, malformed references fail immediately and never reach auth or manifest resolution.
Prevention Tips
Normalize image names in scripts and CI templates before invoking Docker.
Avoid constructing references from unvalidated user input or partially empty variables.