InvalidImageName: The image reference in the pod spec is not a syntactically valid image name

InvalidImageName means the image string could not be parsed at all — this is a malformed reference, not a missing image. No pull is ever attempted, so there is no registry error to read.

Applies to: All Kubernetes versions, any container runtime

What it means

Before attempting a pull, the kubelet parses the image reference into registry, repository, and tag or digest. If that parse fails, it reports InvalidImageName and stops. This is distinct from ErrImagePull, where the reference was valid and the registry rejected it. Because no network request happens, the events contain a parse error rather than anything from a registry. The usual culprits are mechanical: an uppercase letter in the repository path, which the reference grammar does not allow; a stray space or newline introduced by templating; a variable that did not get substituted, leaving something like ${IMAGE_TAG} in the string; or a tag and a digest both specified in an incompatible way.

Most common causes

• Uppercase characters in the repository portion of the reference. Registry paths must be lowercase.
• An unsubstituted template variable left in the image field by Helm, Kustomize, or a CI pipeline.
• A leading or trailing space or newline, often from a YAML block scalar or a shell variable.
• A double colon, an empty tag after the colon, or a tag containing characters the grammar forbids.
• A malformed digest — the wrong length, or missing the sha256: prefix.
• A registry hostname with a scheme attached, such as https://registry.example.com/app. The scheme is not part of an image reference.

How to diagnose it

1. Read the exact string Kubernetes received rather than the one you think you set: kubectl get pod POD -o jsonpath='{.spec.containers[*].image}'.
2. Look at the event message in kubectl describe pod POD, which names the invalid reference.
3. Check for whitespace explicitly — pipe the jsonpath output through cat -A or wrap it in quotes to make trailing characters visible.
4. If the manifest is templated, render it locally and inspect the result: helm template or kubectl kustomize.

How to fix it

1. Lowercase the repository path. Only the tag may contain uppercase characters.
2. Fix the templating so the variable is actually substituted, and add a rendering check to CI so an unsubstituted value fails the pipeline rather than the cluster.
3. Strip whitespace and remove any URL scheme from the registry hostname.
4. Use either a tag or a digest, formatted correctly — repo:tag or repo@sha256:….

Notes

Because this failure happens before any network access, it is completely deterministic and will never resolve by retrying. A pod in this state is waiting for a spec change, not for a transient condition to clear.

Related

• ErrImagePull — The pull was attempted and failed
• ErrImageNeverPull — The image is absent and the pull policy forbids pulling it

Sources

• Kubernetes documentation — Images
• Kubernetes documentation — Debug Pods
• OCI Distribution Specification