Docker "docker tag: Error parsing reference" in CI
docker tag could not parse the target reference. Error parsing reference: <ref> is not a valid repository/tag means the new tag string is malformed - an empty interpolated variable, uppercase in the repo, or illegal characters in the tag.
What this error means
A docker tag <source> <target> fails with Error parsing reference: "<target>" is not a valid repository/tag: invalid reference format. The source may be fine; the target string is bad.
docker tag myorg/api:1.4.2 ghcr.io/myorg/api:
Error parsing reference: "ghcr.io/myorg/api:" is not a valid repository/tag: invalid reference format
# the tag after ':' was an empty $VERSIONCommon causes
An empty tag from an unset variable
A target like repo:${VERSION} with VERSION unset becomes repo:, which has no tag and fails parsing.
Uppercase or illegal characters in the target
The target repository must be lowercase; tags allow a limited character set. Anything outside that is rejected.
A malformed registry/host portion
A stray slash, double colon, or bad host in the target reference breaks parsing.
How to fix it
Build a valid, non-empty target reference
Default the tag and lowercase the repository before tagging.
TAG="${VERSION:-latest}"
docker tag myorg/api:1.4.2 ghcr.io/myorg/api:"$TAG"Validate the reference before tagging
Echo the computed target so an empty/invalid value is obvious in logs.
TARGET="ghcr.io/myorg/api:${VERSION:?VERSION is required}"
echo "tagging -> $TARGET"
docker tag myorg/api:1.4.2 "$TARGET"How to prevent it
- Default or require tag variables so the target is never
repo:. - Lowercase computed repository names before tagging.
- Echo the computed reference for visibility in CI logs.