Google CloudMid

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 found
  • Failed to do request: Head "IMAGE_ADDRESS": dial tcp: lookup gcr.io on REGISTRY_IP_ADDRESS: server misbehaving
  • Failed to do request: Head "IMAGE_ADDRESS": dial tcp REGISTRY_IP_ADDRESS: i/o timeout
  • Unknown 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

  1. 1
    Get the full event message
    kubectl describe pod POD_NAME

    Match the tail of the message to the list below.

  2. 2
    Check 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.

  3. 3
    Check DNS from a node or a debug pod
    nslookup REGISTRY_HOST

    A server misbehaving in the event points at DNS.

Causes and fixes

  • The image or tag does not exist

    HOW TO TELL
    not found with the image address, or a could 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

Sources

Google Cloud documentation (docs.cloud.google.com), read 18 Nov 2026.

Search

Search cheat sheets and projects