Kubernetes "InvalidImageName" - Fix Malformed Image References

By Kaveh Alemi·Latchkey

The kubelet could not even parse the image reference - it is malformed. Usually an unsubstituted template variable, a double colon, or illegal characters made it into the image: field.

What this error means

A pod shows STATUS: InvalidImageName and never attempts a pull. kubectl describe pod reports it could not parse the image reference.

Failed to apply default image tag "myrepo/api:${IMAGE_TAG}": couldn't parse
image reference "myrepo/api:${IMAGE_TAG}": invalid reference format

Common causes

Unsubstituted variable in the image field

A templating step did not replace ${IMAGE_TAG} (or {{ .Values.tag }}), leaving a literal placeholder that is not a valid reference.

Malformed reference

A double tag (api:1.0:latest), uppercase in the repository, or stray whitespace/quotes produces an invalid reference format.

How to fix it

Inspect the rendered image value

Check what actually landed in the manifest, not what you intended.

kubectl get pod <pod> -o jsonpath='{.spec.containers[0].image}'; echo

Fix the substitution and validate

1. Ensure the templating/envsubst step actually ran and the variable was set.
2. Use lowercase repository names and a single valid tag or digest.
3. Validate manifests with kubectl apply --dry-run=client before deploying.

How to prevent it

• Fail the pipeline if image variables are unset before rendering.
• Render and inspect the final manifest in CI.
• Use lowercase, single-tag (or digest) references.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation