阅读中文版本

Kubernetes InvalidImageName — Malformed Image Reference

Fix InvalidImageName by correcting the registry, tag, or digest syntax and ensuring image substitution produces a valid reference.

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

docker pull <image>

Symptoms

This guide profiles the failure behind “Kubernetes InvalidImageName — Malformed Image Reference”. It walks through the observable symptoms, a reproducible diagnosis path, the underlying root cause, the concrete fix, and how to verify the change and prevent a regression.

Observed symptoms include:

• Pod stuck in ImagePullBackOff with reason InvalidImageName
• The image string looks valid but has an extra space or colon
• A templated tag renders empty in the deployed manifest

Reproduce and Diagnose

Reproduce the failure in isolation before changing any code. Work through the checks below in order; each one narrows the search space.

Step 1: Read the exact image from the pod

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

The rendered image string, not the template, shows the malformed reference.

Step 2: Test the reference locally

docker pull <image>

A local pull failure with the same string confirms the syntax problem.

Likely contributors, in order of frequency:

• A trailing space, double colon, or unquoted colon breaks the reference syntax
• A template variable substituted to an empty tag, producing “repo/name:”
• A digest is used without the required @sha256: prefix

Root Cause

Kubernetes parses the container image field strictly as repository[:tag][@digest]. An empty tag, stray whitespace, or a malformed digest makes the reference invalid, so the kubelet never attempts a pull and reports InvalidImageName.

The Fix

Remove stray whitespace, quote values containing colons in YAML/templates, default empty tags to a concrete value such as latest or a pinned version, and format digests as repository@sha256:hex.

Watch out: Defaulting to latest makes deployments non-reproducible; pin immutable tags or digests in production.

spec:
  containers:
    - name: app
      # ❌ image: myrepo/app:              (empty tag)
      # ❌ image: myrepo/app :1.0          (stray space)
      image: myrepo/app:1.0.0             # ✅ tag
      # or pin by digest
      # image: myrepo/app@sha256:abcd...

Verify and Prevent

Apply the corrected manifest and confirm the pod pulls and starts; verify the image string matches a reference you successfully pulled.

Once verified, add a regression test that reproduces the original symptom so the failure cannot silently return.

This class of failure is usually environmental rather than pure logic, so capture the exact command, the environment variables, and the working directory in your bug report. Reproduce it in the smallest possible script, then widen the scope only once the minimal case is understood. A short written checklist for this failure mode saves hours the next time it appears.