A Docker image reference looks like the simplest string in your build pipeline. nginx:latest. Six characters, copy-paste, done. So when your CI fails to pull an image at 2 a.m., you almost never blame the reference itself. You blame the network, the registry, the node. You re-run the build, the cache is warm this time, and the failure doesn’t recur. The tag was wrong the whole time.
This is the problem with image references: they are not a string, they are a grammar. Docker’s reference parser expects a REGISTRY/REPOSITORY:TAG structure with strict character classes at each position. A capital letter in the repository name is technically allowed by the spec but rejected by Docker Hub. An empty tag after the colon is a syntax error in Compose and a silent fallback in docker run. A digest without an algorithm prefix passes your IDE’s regex and fails at the daemon.
The Docker Image Tag Validator on Elysia Tools applies the same reference grammar that distribution/reference uses in Go, the same character-class rules Docker Hub enforces for uploads, and the same digest-shape checks that the daemon performs before requesting a manifest. Paste an image reference, get a verdict for every component: registry hostname, repository path, tag, digest, and the implicit latest fallback. It is a tool for catching the typo your cache has been quietly papering over.
What the validator actually checks
When you submit docker.io/library/nginx:1.27-alpine, the tool breaks the reference into four parts and validates each against its own ruleset.
Registry hostname. The leading slash-separated token must be a valid DNS name or one of Docker’s well-known shorthands. docker.io, localhost, and *.amazonaws.com are accepted as-is. Anything else must resolve to lowercase letters, digits, dots, and dashes per RFC 1123. A common failure: Docker.io/library/nginx — capitalized registry names are accepted by some clients and rejected by others, depending on whether the daemon normalizes the hostname before the lookup.
Repository path. After the registry comes /-separated path components. Each component is restricted to lowercase alphanumerics, dots, dashes, and underscores. No consecutive separators, no leading dash, no uppercase. The validator catches two classes of bug here: accidental capitalization from copy-paste (MyApp/api instead of myapp/api) and path components that start with a separator or contain ...
Tag. The :tag suffix is optional in the spec but mandatory in practice for any image you intend to pin. Tags must match [A-Za-z0-9_][A-Za-z0-9_.-]{0,127}. The first character rule trips people up — :v1.0 works, but :.v1.0 is rejected by the daemon even though most regexes let it through. The validator surfaces this as a length-zero error on the tag portion.
Digest. The @sha256:... suffix is an alternative to a tag, not an addition. A reference with both :tag and @sha256:... is a pinned immutable reference; the daemon prefers the digest and ignores the tag for content addressing. The validator verifies the digest prefix is one of the supported algorithms (sha256, sha384, sha512) and that the hex body matches the expected length.
The five references that fail in production and pass in your editor
Here are five image references that look fine in a YAML file but break at the daemon. The validator flags all five; a plain text search flags none of them.
myApp/api:v1.2.3 — capital A in the repository component. Docker Hub returns 404 because it lowercases on storage; the validator catches the uppercase character at the path-component level and warns that the push will succeed but the pull will not.
registry.internal:5000/team/app: — empty tag. The trailing colon makes the parser enter tag-parsing mode and reject an empty string. docker pull returns invalid reference format; Compose reports the same error during dependency resolution. The validator flags tag="" and suggests :latest as the explicit fallback.
nginx@@sha256:abc123... — double @. This is a malformed digest reference that some parsers split as tag="" digest="@sha256:abc..." and others reject entirely. The validator recognizes the double-@ pattern as a structural error before attempting any algorithm check.
gcr.io/my-project/image:v1@sha256:... — tag and digest together without a separator character count. This is actually valid syntax, but the validator warns that the tag will be ignored on pull and the digest is the binding identifier. Useful as a reminder when you think you are upgrading by bumping the tag.
ghcr.io/org/repo:feature_branch — valid by spec, dangerous in practice. Tags that look like git branch names are mutable. Two CI runs that resolve the same tag at different times can pull different bytes. The validator does not reject this — the spec allows it — but the report includes a mutable-tag advisory that pairs well with the digest check.
Where this catches what your build does not
The bug pattern this validator targets is the one where the build cache hides a broken reference. Docker’s layer cache is keyed by reference, not by content address, so once a broken-but-resolvable tag enters the cache, subsequent builds use the cached layers without re-resolving the manifest. The reference is wrong, but the daemon never re-checks because the layers are already local.
Three places this matters:
Multi-stage builds where the final stage copies from a tag that was correct when the build was first written. The cache holds the layers; the registry holds something else. Running the validator against every FROM line in a Dockerfile — pasting each one into the tool — surfaces these mismatches before they become incident reports.
Kubernetes manifests with templated image references. Helm and Kustomize both interpolate strings; a typo in a values file or a base override propagates silently until the first reconcile. The validator as a pre-commit hook (manual today, but the verification surface is the same) catches the typo before it reaches the cluster.
CI matrix builds that fan out across registries. If your matrix lists $REGISTRY/$REPO:$TAG and one registry’s name has a typo, that matrix entry fails alone. The validator against the rendered string — after variable substitution — tells you whether the failure is the image or the reference.
Pairing the validator with the Elysia Tools sample set
The Docker image tag samples are a small corpus of references across registries, repositories, tags, and digests — the same shape you see in a real multi-service application. Run each sample through the validator to see which reference forms pass, which fail, and which pass-with-warning. It is a faster way to internalize the grammar than reading the distribution reference spec, because the validator outputs the same errors the daemon will output, in the same order.
Closing thought
An image reference is a contract between your build system and the daemon. Most tools that touch it — editors, linters, even docker pull with a warm cache — accept a wider grammar than the daemon actually enforces. The validator narrows that gap by running the same parser the daemon runs and reporting what the daemon would say. Use it during Dockerfile review, in pre-commit hooks, and during incident triage when the obvious causes have been ruled out and the not-obvious causes look like the build cache.
You can find the Docker Image Tag Validator and the rest of the validation toolkit at elysiatools.com/en/tools.
