InvalidImageName means the container image reference format is invalid. Remove protocol prefixes, use lowercase names, and ensure proper registry/image/tag format.
InvalidImageName occurs when Kubernetes cannot parse the container image reference in your pod specification. The image string doesn't follow the expected format, preventing the kubelet from even attempting to pull the image. This is a validation error, not a network or authentication issue. The image reference itself is malformed—it might contain protocol prefixes, invalid characters, or improper formatting that the container runtime cannot interpret.
View what Kubernetes is trying to use:
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].image}'
# Or describe to see the error
kubectl describe pod <pod-name>Look for:
- Protocol prefixes (https://, docker://)
- Uppercase letters
- Double slashes
- Unusual characters
Image references should not include protocols:
# Wrong
image: https://docker.io/nginx:latest
image: docker://nginx:latest
# Correct
image: docker.io/nginx:latest
image: nginx:latestContainer registries are accessed via their domain, not URL scheme.
Image references must be lowercase:
# Wrong
image: Docker.io/Nginx:Latest
image: myregistry.com/MyApp:v1
# Correct
image: docker.io/nginx:latest
image: myregistry.com/myapp:v1Both the registry, image name, and tag should be lowercase.
Ensure clean path structure:
# Wrong - double slash
image: myregistry.com//myimage:tag
# Wrong - trailing slash
image: myregistry.com/myimage/:tag
# Correct
image: myregistry.com/myimage:tag
image: myregistry.com/namespace/myimage:tagHelm can interpret numeric tags as numbers, causing invalid formats:
# values.yaml - Wrong (may become scientific notation)
image:
repository: myregistry.com/myapp
tag: 45980468
# Correct - quote the tag
image:
repository: myregistry.com/myapp
tag: "45980468"In templates:
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"Valid image reference formats:
# Docker Hub official images
image: nginx:1.21
# Docker Hub user images
image: myuser/myapp:latest
# Private registry
image: myregistry.com:5000/myapp:v1.0
# With digest instead of tag
image: nginx@sha256:abc123...
# Full format
image: registry.example.com/namespace/image:tagTest locally:
docker pull <your-image-reference>Image reference format: [registry/][namespace/]image[:tag|@digest]
Components:
- registry: Optional, defaults to docker.io
- namespace: Optional, defaults to library for Docker Hub
- image: Required, must be lowercase
- tag: Optional, defaults to latest
- digest: Alternative to tag, immutable reference
Special cases:
- nginx → docker.io/library/nginx:latest
- myuser/myapp → docker.io/myuser/myapp:latest
- gcr.io/project/image → Uses specified registry
For CI/CD pipelines, always quote image tags in YAML to prevent type coercion. Use string interpolation carefully to avoid introducing spaces or invalid characters.
When using variable substitution, validate the final image reference before deployment:
kubectl apply --dry-run=client -f deployment.yamlNo subnets found for EKS cluster
How to fix "eks subnet not found" in Kubernetes
unable to compute replica count
How to fix "unable to compute replica count" in Kubernetes HPA
error: context not found
How to fix "error: context not found" in Kubernetes
default backend - 404
How to fix "default backend - 404" in Kubernetes Ingress
serviceaccount cannot list resource
How to fix "serviceaccount cannot list resource" in Kubernetes