GKE image pull fails: not found, DNS, timeout or slow pulls
When an image pull fails without a 401 or 403, the cause is the image reference, DNS, a firewall or egress path, or a slow pull. Match the event message.
What you see
"IMAGE_ADDRESS": not foundFailed to do request: Head "IMAGE_ADDRESS": dial tcp: lookup gcr.io on REGISTRY_IP_ADDRESS: server misbehavingFailed to do request: Head "IMAGE_ADDRESS": dial tcp REGISTRY_IP_ADDRESS: i/o timeoutUnknown desc = context canceled
What it means
Pull failure messages share a prefix: Failed to pull image "IMAGE_ADDRESS": rpc error: code = CODE = failed to pull and unpack image .... The tail names the failing step: resolving the reference, reaching the registry, or downloading layers.
Google's status meanings: ErrImagePull is a general error during the pull, InvalidImageName means the name is not valid, and RegistryUnavailable is typically a network connectivity issue.
How to confirm the cause
- 1Get the full event message
kubectl describe pod POD_NAME
Match the tail of the message to the list below.
- 2Check the image exists in the registry
gcloud artifacts docker images list REPOSITORY_PATH
Replace with your Artifact Registry repository path. Check the tag as well as the name.
- 3Check DNS from a node or a debug pod
nslookup REGISTRY_HOST
A
server misbehavingin the event points at DNS.
Causes and fixes
The image or tag does not exist
- HOW TO TELL
not foundwith the image address, or acould not fetch content descriptor ... not found.- ROOT CAUSE
- The name, repository path or tag in the manifest does not match anything in the registry, or the image was never pushed.
- FIX
- Correct the reference or push the image. Pin tags so a missing one is caught early.
DNS resolution fails
- HOW TO TELL
lookup gcr.io on ... server misbehaving.- ROOT CAUSE
- The node's resolver cannot resolve the registry host.
- FIX
- Investigate DNS resolution on the node and cluster DNS.
Firewall or egress blocks the registry
- HOW TO TELL
dial tcp ...: i/o timeout, or a node bootstrap failure.- ROOT CAUSE
- Traffic to the registry is blocked by a firewall rule or has no path out of a private cluster.
- FIX
- Check the firewall configuration and the egress path from the nodes to the registry, including how a private cluster reaches it.
Slow pulls or timeouts
- HOW TO TELL
Unknown desc = context canceled.- ROOT CAUSE
- A very large image, or slow network, takes longer than the pull allows.
- FIX
- Reduce the image size and check network throughput to the registry.
How to stop it coming back
- Keep images small.
- Put the registry in the same region as the cluster.
- Add a CI check that the image reference in the manifest exists.
Keep going
- Runbook: GKE ImagePullBackOff: 401 or 403 pulling from the registry
- Runbook: ImagePullBackOff: the pod can't pull its image
- Runbook: Host can't resolve names: temporary failure in name resolution
- Cheat sheet: gcloud
- Cheat sheet: kubectl
- Lesson: the kubernetes topic in Learn
Sources
Google Cloud documentation (docs.cloud.google.com), read 18 Nov 2026.