🚨 Kubernetes Error Guide: 'InvalidImageName' Malformed Image Reference

Exact Error Message

NAME                      READY   STATUS             RESTARTS   AGE
web-6c4d9b7f8c-2trqp      0/1     InvalidImageName   0          18s

# kubectl describe pod web-6c4d9b7f8c-2trqp
Events:
  Type     Reason         Age               From     Message
  ----     ------         ----              ----     -------
  Warning  InvalidImageName  9s (x3 over 18s)  kubelet
    Failed to apply default image tag "registry.example.com/team/App:v1.2 ":
    couldn't parse image reference "registry.example.com/team/App:v1.2 ":
    invalid reference format

What the Error Means

InvalidImageName is reported by the kubelet when the image string in your pod spec is not a syntactically valid container image reference. Unlike ErrImagePull or ImagePullBackOff, the kubelet never even attempts to contact a registry — the reference fails parsing locally, so the pull cannot start. The container status reason is set to InvalidImageName and the pod sits at 0/1 indefinitely.

A valid reference looks like [registry[:port]/]repository[:tag][@digest]. The repository path must be lowercase, the tag must match a restricted character set, and there must be no whitespace, no double slashes, and no illegal characters. Any deviation triggers invalid reference format.

Common Causes

• Trailing or leading whitespace in the image string, often from a YAML multiline block or a templating mistake ("myimage:v1 ").
• Uppercase letters in the repository path. Docker/OCI repository names must be lowercase; team/App is invalid.
• A malformed or empty tag — myimage: with nothing after the colon, or a tag containing illegal characters like spaces.
• Double slashes or missing components from string concatenation in Helm/Kustomize, e.g. registry.example.com//app:v1.
• An unresolved template variable that left literal text like myimage:{{ .Values.tag }} or myimage:${TAG} in the spec.
• A digest with a typo — @sha256: followed by a non-64-hex string.

How to Reproduce the Error

Apply a pod whose image has an uppercase repo and a trailing space:

apiVersion: v1
kind: Pod
metadata:
  name: bad-image
spec:
  containers:
    - name: app
      image: "registry.example.com/team/App:v1.2 "

kubectl apply -f bad-image.yaml
kubectl get pod bad-image
# STATUS: InvalidImageName

Diagnostic Commands

# Confirm the status reason
kubectl get pod <POD> -o jsonpath='{.status.containerStatuses[0].state.waiting.reason}{"\n"}'

# See the exact rejected reference in events
kubectl describe pod <POD> | grep -iE 'invalidimagename|invalid reference'

# Print the raw image string with delimiters to reveal hidden whitespace
kubectl get pod <POD> -o jsonpath='{range .spec.containers[*]}[{.image}]{"\n"}{end}'

# Check init containers too
kubectl get pod <POD> -o jsonpath='{range .spec.initContainers[*]}[{.image}]{"\n"}{end}'

# Inspect the owning workload to find the source of the bad value
kubectl get deployment <DEPLOY> -o jsonpath='{.spec.template.spec.containers[*].image}{"\n"}'

# If templated, render and grep the manifest before applying
helm template <RELEASE> ./chart | grep -n 'image:'

Step-by-Step Resolution

1. Print the exact image string with delimiters. Wrapping it in brackets exposes leading/trailing spaces that are invisible in normal output:

kubectl get pod <POD> -o jsonpath='{range .spec.containers[*]}[{.image}]{"\n"}{end}'

If you see [registry.example.com/team/App:v1.2 ], the trailing space and the uppercase App are both invalid.

2. Fix the reference to a valid form. Lowercase the repository, strip whitespace, and ensure a proper tag:

registry.example.com/team/app:v1.2

3. Patch the workload, not the pod. Pods owned by a Deployment are immutable for image edits in practice — update the controller:

kubectl set image deployment/<DEPLOY> app=registry.example.com/team/app:v1.2

4. If the value comes from a template, fix the source. Render the chart and confirm the substitution resolved:

helm template <RELEASE> ./chart | grep 'image:'

Make sure .Values.image.tag is set and that you are not concatenating a registry with a trailing slash.

5. Re-check the status. The reason should clear once the reference parses and the kubelet moves on to pulling:

kubectl get pod -l app=<APP> -w

Prevention and Best Practices

• Always quote image strings in YAML and trim whitespace in templating helpers ({{ .Values.image | trim }}).
• Keep repository paths lowercase; configure a CI lint step that rejects uppercase or whitespace in image: fields.
• Render Helm/Kustomize output in CI (helm template, kustomize build) and validate every image: against the OCI reference grammar before deploy.
• Pin images by digest where possible, and validate the digest is exactly sha256: plus 64 hex characters.
• Use admission policies (OPA/Gatekeeper or Kyverno) to require a registry prefix and reject malformed references cluster-wide. See more in Kubernetes & Helm guides.

Related Errors

• ErrImagePull / ImagePullBackOff — the reference was valid but the registry could not serve the image.
• ImageInspectError — the image exists locally but the runtime failed to inspect its metadata.
• CreateContainerConfigError — the image is fine but a referenced ConfigMap/Secret is missing.
• ErrImageNeverPull — a valid image with imagePullPolicy: Never that is not present on the node.

Frequently Asked Questions

Why does the kubelet not even try to pull the image? Because the reference fails to parse before any registry call. The kubelet validates the image string syntax first; if it is malformed, there is no host or path to contact, so it short-circuits with InvalidImageName.

My image works with docker run but Kubernetes rejects it. Why? Some Docker CLI conveniences (like normalizing case or trimming whitespace) are not applied identically by every container runtime under Kubernetes. The safest path is a fully explicit, lowercase, whitespace-free reference.

Can a tag have uppercase letters? Tags allow uppercase and a limited set of symbols, but the repository path must be lowercase. Many InvalidImageName cases are actually uppercase in the path, not the tag.

How do I catch this before it hits the cluster? Lint rendered manifests in CI. Run kubeconform or a custom check that parses each image: value with an OCI reference parser, failing the pipeline on any invalid format.