Bitbucket "Failed to pull image" / Image Not Found

By Kaveh Alemi·Latchkey

Bitbucket could not pull the Docker image you set for the step. Either the name/tag is wrong, the image is private and has no credentials, or the registry pull hit a transient error.

What this error means

The step never reaches your script - it fails at setup with a "failed to pull image" or "manifest unknown" error. A bad tag fails every time; a registry blip fails intermittently and passes on retry.

Failed to pull image "myorg/builder:lateset":
manifest for myorg/builder:lateset not found.

Common causes

Wrong image name or tag

A typo in the repository or tag (lateset vs latest), or a tag that no longer exists, makes the registry return "manifest unknown".

Private image without credentials

A private registry image needs username/password (or AWS/GCR auth) declared on the image. Without it, the pull is unauthorized.

How to fix it

Use a correct, existing tag

image: myorg/builder:latest
# or pin a digest for reproducibility
# image: myorg/builder@sha256:...

Authenticate to a private registry

Provide registry credentials via secured variables on the image definition.

image:
  name: myorg/builder:latest
  username: $DOCKER_USERNAME
  password: $DOCKER_PASSWORD

How to prevent it

• Pin images to a stable tag or digest you control.
• Store registry credentials as secured variables.
• Mirror critical base images so an upstream outage does not block CI.

Frequently asked questions

Related guides

References

• GitHub Actions documentation