Kubernetes InvalidImageName

Step-by-Step Troubleshooting

1. Identify the Invalid Image Reference

kubectl describe pod <pod-name> -n <namespace>

Check the container spec and events for the malformed image string:

Containers:
  app:
    Image:      {{ .Values.image.repository }}:{{ .Values.image.tag }}
    ...
Events:
  Warning  InspectFailed  couldn't parse image reference "{{ .Values.image.repository }}:{{ .Values.image.tag }}": invalid reference format

2. Extract the Exact Image String

kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].image}'

This shows the literal image string Kubernetes is trying to use. Common invalid patterns:

# Unrendered template
{{ .Values.image }}:{{ .Values.tag }}

# Empty string
(empty)

# Protocol included
https://myregistry.io/app:v1

# Spaces
my-registry.io / app : v1

# Invalid tag format
myregistry.io/app:v1 beta

3. Validate the Image Reference Format

A valid container image reference follows this format:

[registry-host[:port]/]repository[:tag]
[registry-host[:port]/]repository[@digest]

Valid examples:

nginx
nginx:1.25
library/nginx:1.25
docker.io/library/nginx:1.25
myregistry.io:5000/team/app:v1.0
ghcr.io/org/app@sha256:a1b2c3d4e5f6...

Invalid examples:

https://docker.io/nginx        # No protocol scheme
nginx:                         # Empty tag
NGINX:latest                   # Uppercase (depends on runtime)
my app:v1                      # Space in name
nginx@sha256:abc               # Truncated digest

4. Check Template Rendering

If you use Helm, Kustomize, or another templating tool, verify the output.

# Helm: render templates locally
helm template <release-name> <chart-path> --debug | grep "image:"

# Kustomize: build and check
kubectl kustomize <path> | grep "image:"

# Check for missing values
helm template <release-name> <chart-path> --set image.repository=myapp --set image.tag=v1 | grep "image:"

If the template variables are not set, the rendered output will contain literal template syntax.

5. Fix the Image Reference

Update the deployment with a valid image reference:

# Set the correct image
kubectl set image deployment/<deploy-name> <container-name>=myregistry.io/app:v1.0

# Or edit the deployment directly
kubectl edit deployment <deploy-name>

For Helm deployments, fix the values file:

# values.yaml
image:
  repository: myregistry.io/app
  tag: "v1.0"

Then redeploy:

helm upgrade <release-name> <chart-path> -f values.yaml

6. Fix Empty Image Fields

If the image field is empty, it usually means a required value is missing.

# Check if the image field is empty
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].image}'

# Trace back to the source: deployment, helm values, etc.
kubectl get deployment <deploy-name> -o jsonpath='{.spec.template.spec.containers[0].image}'

Ensure your CI/CD pipeline passes the image reference as a parameter:

# Example: setting image during Helm install
helm install myapp ./chart --set image.repository=myregistry.io/app --set image.tag=v1.0

7. Validate Image References in CI

Add validation to your CI pipeline to catch invalid image references before they reach the cluster.

# Use crane to validate an image reference
crane validate --remote myregistry.io/app:v1.0

# Use kubeval or kubeconform to validate manifests
kubeconform -strict deployment.yaml

# Simple regex validation in bash
IMAGE="myregistry.io/app:v1.0"
if [[ ! "$IMAGE" =~ ^[a-z0-9]([a-z0-9._/-]*[a-z0-9])?(:[a-zA-Z0-9._-]+)?(@sha256:[a-f0-9]{64})?$ ]]; then
  echo "Invalid image reference: $IMAGE"
  exit 1
fi

8. Use Admission Controllers

Deploy a validating admission webhook to reject pods with invalid image references before they are created.

# Example Kyverno policy
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: validate-image-reference
spec:
  validationFailureAction: Enforce
  rules:
    - name: check-image-format
      match:
        any:
          - resources:
              kinds:
                - Pod
      validate:
        message: "Image reference must include a valid registry, repository, and tag."
        pattern:
          spec:
            containers:
              - image: "?*/?*:?*"

9. Verify the Fix

# Watch the pod
kubectl get pods -w

# Confirm the image is valid and pulling
kubectl describe pod <pod-name> | grep -E "Image:|Events" -A5

The pod should transition to ContainerCreating (image pulling) and then to Running.