Kubernetes "InvalidImageName": what triggers it and how to fix
Explains and fixes the Kubernetes InvalidImageName error. Use when pods fail with invalid image name errors, when image references work in Docker but not Kubernetes, or when validating image naming. Not for pull failures of valid names.
TL;DR
InvalidImageName means the image reference violates the naming rules: uppercase characters, invalid characters, or a malformed registry/organization path. Docker is lenient about some forms that the Kubernetes image parser rejects. The fix is mechanical: lowercase everything, strip invalid characters, and use the full registry path format. It is always the string, never the registry.
The query
Kubernetes "InvalidImageName": what triggers it and how to fixUse this when
- Pods fail with InvalidImageName
- An image reference works in Docker but fails in Kubernetes
- Validating image naming conventions
- After renaming images or registries
Not for when
- ImagePullBackOff (the name is valid, the pull fails)
- Registry authentication issues
- Tag not found errors
Steps
Step 1: Read the exact image string
Get the image field from the pod spec exactly as specified. The error is about this string; eyeball it for uppercase letters, spaces, or odd characters before theorizing. Expected output: the offending string in hand.
Step 2: Check the naming rules
Image names must be lowercase, with components separated by slashes, and tags following the colon must match the tag rules. Common violations: uppercase in the repository name, underscores in weird places, or empty components from bad templating. Expected output: the specific rule violation identified.
Step 3: Look for templating artifacts
Helm and kustomize templating can produce broken image strings: empty variables leaving double slashes or trailing colons, unquoted values. Render the template and inspect the image field in the output. Expected output: the templating bug found, or templating ruled out.
Step 4: Fix and use the canonical form
Rewrite as registry/organization/image:tag, all lowercase, explicit tag (never rely on implicit latest in production). Apply and verify the pod leaves the invalid state. Expected output: the pod accepted and pulling.
Step 5: Lint image names in CI
Add a check that validates image references in manifests before they reach the cluster. InvalidImageName is a build-time catchable error; it should never page anyone. Expected output: bad image strings caught at PR time.
Provenance
Resolved from the public thread: https://vectle.com/posts/pstnkDBOUGgrqYE2teApEu0A