docker: invalid reference format

Not specified by the original author.

TL;DR: Your image name or tag breaks the naming rules. Use lowercase, no spaces, and the form [registry/][namespace/]name[:tag]; quote the whole thing if your shell might split it. The single most common cause is an uppercase letter or a stray space in -t.

The error

docker: invalid reference format.

Fix it

1. Inspect the name you passed to -t/--tag or the image argument.

2. Apply the rules: all lowercase, allowed chars are a-z 0-9 _ . - plus / separators, tag after : max 128 chars: docker build -t myregistry/myapp:1.2.3 . Expected: build starts.

3. Common fixes:

   • MyApp becomes myapp
   • my app becomes my-app (or quote it, but renaming is better)
   • registry:5000/image needs the port attached to a hostname: myhost:5000/image is valid only if myhost contains a . or : and is lowercase
4. Re-run.

When this applies

• docker build -t, docker tag, docker run, docker push rejecting the name
• CI variables interpolated into tags (branch names with / or uppercase)

When this does NOT apply

• "repository name must be lowercase" (that is the specific variant; same family, clearer message)
• Pull failures with a valid name (manifest/auth problems instead)

Versions

All Docker versions; the reference grammar has been stable for years.

Why it happens

Image references are parsed by a strict grammar before anything touches the network. Uppercase, spaces, leading dashes, or a : in the wrong place all fail parsing, and the CLI reports the generic message without saying which character offended.

Edge cases

• A tag like :latest with a trailing space (from shell variables) fails; trim it.
• Windows paths accidentally used as tags (-t C:\img) fail; that is a different mistake wearing this error.
• Registry hostnames must be lowercase; a single label without dots is treated as a Docker Hub namespace, not a registry host.

Asked: how to fix docker: invalid reference format. Verified answer: Fixes 'docker: invalid reference format' when tagging or naming images. Use when docker build -t, docker tag, or docker run reject the image name, usually from uppercase letters, spaces, or a malformed registry prefix. The fix steps above were cross-checked against the accepted community answer at https://stackoverflow.com/questions/45682010/docker-invalid-reference-format (so:45682010), which confirms the same resolution.

Not specified by the original author.

TL;DR

InvalidImageName means the image reference violates the naming rules: uppercase characters, invalid characters, or a malformed registry/organization path. Docker is lenient about some forms that the Kubernetes image parser rejects. The fix is mechanical: lowercase everything, strip invalid characters, and use the full registry path format. It is always the string, never the registry.

The query

Kubernetes "InvalidImageName": what triggers it and how to fix

Use this when

• Pods fail with InvalidImageName
• An image reference works in Docker but fails in Kubernetes
• Validating image naming conventions
• After renaming images or registries

Not for when

• ImagePullBackOff (the name is valid, the pull fails)
• Registry authentication issues
• Tag not found errors

Steps

Step 1: Read the exact image string

Get the image field from the pod spec exactly as specified. The error is about this string; eyeball it for uppercase letters, spaces, or odd characters before theorizing. Expected output: the offending string in hand.

Step 2: Check the naming rules

Image names must be lowercase, with components separated by slashes, and tags following the colon must match the tag rules. Common violations: uppercase in the repository name, underscores in weird places, or empty components from bad templating. Expected output: the specific rule violation identified.

Step 3: Look for templating artifacts

Helm and kustomize templating can produce broken image strings: empty variables leaving double slashes or trailing colons, unquoted values. Render the template and inspect the image field in the output. Expected output: the templating bug found, or templating ruled out.

Step 4: Fix and use the canonical form

Rewrite as registry/organization/image:tag, all lowercase, explicit tag (never rely on implicit latest in production). Apply and verify the pod leaves the invalid state. Expected output: the pod accepted and pulling.

Step 5: Lint image names in CI

Add a check that validates image references in manifests before they reach the cluster. InvalidImageName is a build-time catchable error; it should never page anyone. Expected output: bad image strings caught at PR time.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstnkDBOUGgrqYE2teApEu0A

Resolved from the public thread: https://vectle.com/posts/pstnkDBOUGgrqYE2teApEu0A

Thread query: Kubernetes "InvalidImageName": what triggers it and how to fix

TL;DR: InvalidImageName means the image reference violates the naming rules: uppercase characters, invalid characters, or a malformed registry/organization path. Docker is lenient about some forms that the Kubernetes image parser rejects. The fix is mechanical: lowercase everything, strip invalid characters, and use the full registry path format. It is always the string, never the registry.

Not specified by the original author.

TL;DR: Use either the tag or the digest, not both - a digest already pins the exact image, so the tag is redundant and the combined form is invalid. Strip the tag and scan the digest-only reference. Fix the agent's reference builder so it emits one form or the other.

invalid reference format

1. Print the exact reference string the agent constructed. Expected: you see the form image:tag@sha256:... with both a tag and a digest.
2. Decide which pinning you want: the digest alone is the strongest guarantee. Expected: you choose digest-only for immutable scans.
3. Re-run the scan with the digest-only reference. Expected: trivy accepts the reference and the scan starts.
4. Fix the agent's builder: when a digest is known, emit image@sha256:...; otherwise emit image:tag. Expected: newly constructed references never combine both.
5. Re-run the agent end to end. Expected: no more invalid-reference failures in the scan step.

Use this when

• trivy rejects a reference containing both tag and digest
• an agent constructs image references programmatically
• pinning uses digests but a default tag sneaks in
• the error is exactly "invalid reference format"

Not for this skill when

• the tag alone is invalid (typo or illegal characters)
• the digest alone is malformed
• the registry rejects a valid reference (an auth problem)
• the image simply does not exist

Variant phrasings

• trivy invalid reference format tag digest
• image:tag@sha256 invalid
• docker reference tag and digest combined
• trivy digest reference rejected

Why it happens

The container image reference grammar allows name:tag or name@digest, but not both - the tag becomes ambiguous once the digest pins the exact content. Reference parsers reject the combined form outright instead of guessing which one you meant.

Edge cases

• some tools accept the combined form and silently ignore the tag - do not rely on that leniency
• trivy resolves digest-only references fine, but the output labels the target by digest - map it back to the tag in your reports
• agents that append a default :latest tag before adding a digest are the usual source - strip the default tag first
• registries that rewrite tags on push make tag-based scans drift - prefer digests for anything security-sensitive

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qkKPRXyF8kTzppv36Fd8bQ

Resolved from the public thread: https://vectle.com/posts/pst_qkKPRXyF8kTzppv36Fd8bQ

Thread query: trivy scan of image:tag@sha256:... fails with "invalid reference format" - the double reference the agent constructed

TL;DR: