Docker Core
The image reference string violates the naming rules before any lookup.
invalid-reference-formatReviewed for reference consistency: August 11, 2026
The image reference string violates the naming rules before any lookup.
What invalid-reference-format Means
The invalid-reference-format error on the Docker Core indicates the image reference string violates the naming rules before any lookup.. This typically occurs due to repository names include uppercase letters, which the reference grammar forbids.
Image references follow a grammar: optional registry host, namespace path, repository name, tag, and digest. Uppercase letters in the repository part, stray characters, or an empty name after a host all fail validation locally, and the client rejects the reference before contacting any registry.
How to fix invalid-reference-format
General informational guidance, not professional advice. Commands can affect your system or data — back up first and proceed at your own risk. FixerCode is an independent reference, not affiliated with any vendor mentioned.
Test the reference against the local parser
Inspecting a reference runs the same validation locally; the error text echoes the exact string the parser rejected.
docker image inspect <suspect-reference>Show image references already stored locally
The images listing prints well-formed references as the daemon normalized them, a live grammar example for comparison.
docker images --format 'table {{.Repository}}\t{{.Tag}}'
Technical Background
Validation is client-side and cheap: the reference parser runs before network, auth, or storage, so this error cannot be caused by registry state and always indicates the string itself.
The grammar is published with the image tag command reference. Its rules explain the two most common surprises: repository path components must be lowercase, and a reference carries a tag or a digest in strict forms, with the combined form having its own shape.
Common Causes
- Repository names include uppercase letters, which the reference grammar forbids
- A shell variable expanded to empty, leaving a malformed reference
- The string merges tag and digest syntax in a form the parser cannot attribute
Typical Scenarios
- An organization name pasted with capital letters into an image reference
- A variable expansion producing an empty repository before the colon
- A tag containing characters outside the allowed set
What to Know
Since nothing left the machine, the fix loop is fast: the exact reference echoed in the error, compared against the grammar's component rules, usually exposes the offending character or empty segment immediately.
Frequently Asked Questions
Common questions about Docker invalid-reference-format error
Lowercase is part of the published reference grammar; registries normalize nothing, so the client enforces the rule before a lookup can fail ambiguously.
Yes in the full name:tag@digest form; failures usually come from ad-hoc combinations the parser cannot attribute.
Related Error Codes
Related Errors From Other Categories
Similar error codes documented across different platforms and systems