BahriyaBAHRIYAby Mamluk

Image Cannot Be Pulled

A deployment that fails with an image pull error can't fetch the container image you referenced. The cause is either the image reference itself, or missing or misplaced registry credentials.

Updated 3 Aug 20262 min read

A deployment that fails with an image pull error can't fetch the container image you referenced. The cause is either the image reference itself, or missing or misplaced registry credentials.

Symptoms

  • The deployment reports an image pull error.
  • The container stays in "Provisioning" and never starts. See Deployment Stuck in Provisioning.
  • The image works from one registry or region but not another.

Likely causes

  • The image is private and no registry is configured. Public images need no credentials; private images need a registry (server, username, password).
  • Registry credentials are wrong or expired. The server, username, or password doesn't grant access to the image.
  • The registry isn't deployed to the container's regions. A registry, like a secret, is deployed per region and must be present in every region the container runs in.
  • The image reference is wrong. A typo in the host or name, or a tag that doesn't exist (deleted or overwritten).

How to fix

  1. Check the full image reference, including the registry host and the exact tag. Confirm the image exists by pulling it locally: docker pull <image>.
  2. Add a registry for private images. Configure the registry server, username, and password, and attach it to the container. See Registries.
  3. Verify the credentials grant access to that specific image — pulling it locally with the same credentials confirms they work.
  4. Deploy the registry to every region the container runs in. A registry missing from one region causes pulls to fail there while succeeding elsewhere.
  5. Fix the tag if it was overwritten or removed. Prefer immutable, versioned tags (v1.2.3) over moving tags like latest so a deploy always pulls a known image.
Note

Public images require no registry at all. If your image is public and still won't pull, the reference or the tag is wrong — recheck both before adding credentials.