Bitbucket Cloud · Pipelines · Checked November 2, 2026

Bitbucket Pipelines: "Container 'build' failed to pull image"

Before your script runs, Pipelines pulls the image named in image:, of the step or of the whole file, and starts the build container from it. When the pull fails, the step stops before the first command, with a line like this one from Atlassian's issue BCLOUD-23970:

Container 'build' failed to pull image: 'failed to pull and unpack image "crg.apkg.io/...": failed to resolve reference "crg.apkg.io/...": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed'

The end of the line is the registry's answer. Registries give a wrong name and missing credentials the same words, "repository does not exist or may require authorization", so check both.

The name and the tag

Docker Hub images go by name (node:20, account-name/openjdk:8). Images anywhere else need the full address with the registry's host, from Atlassian's Use Docker images as build environments.
A tag that was never pushed fails the same way as a private image without credentials. Run docker pull with the exact name on your own machine, signed in as the same user the pipeline uses.
The same page says the image has to be reachable from the internet: "internal registries without internet connectivity are not currently supported".
An image name in a variable needs ${{VAR}}, not $VAR (a variable is empty).

Username and password under image

image:
  name: account-name/openjdk:8
  username: $DOCKER_HUB_USERNAME
  password: $DOCKER_HUB_PASSWORD

Other registries take the same two fields with their full address. The email field is deprecated and no longer needed, the page adds.

When the values look right and the pull is still refused, Atlassian's article Failed to pull private image in Bitbucket pipelines (updated September 26, 2025) names the most likely cause: a space at the start or end of the variable. A secured variable cannot be read back, so delete it and create it again.

AWS ECR

Atlassian's page shows two ways. With access keys:

image:
  name: <account-id>.dkr.ecr.<region>.amazonaws.com/openjdk:8
  aws:
    access-key: $AWS_ACCESS_KEY
    secret-key: $AWS_SECRET_KEY

Or with OpenID Connect, which it recommends: aws: oidc-role: with the role's ARN. The page Use AWS ECR images in Pipelines with OpenID Connect also sets oidc: true on the step, and gives the role ecr:GetAuthorizationToken plus read actions on the repository, among them ecr:BatchGetImage, ecr:GetDownloadUrlForLayer and ecr:BatchCheckLayerAvailability. The identity provider and the trust policy work as for any role assumed from Pipelines (OIDC to AWS).

- step:
    image:
      name: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo:latest
      aws:
        oidc-role: arn:aws:iam::123456789012:role/pipelines-ecr-access
    oidc: true
    script:
      - echo "hello world"

One difference from Atlassian's example: it writes the image as ...amazonaws.com/repository/my-repo:latest. An ECR image address has no repository/ part; AWS's Pulling an image writes aws_account_id.dkr.ecr.us-west-2.amazonaws.com/amazonlinux:latest. The repository/ belongs in the policy's ARN, arn:aws:ecr:...:repository/my-repo.

Google Artifact Registry

Atlassian's page still shows Google Container Registry (gcr.io), with _json_key as the username and a service account key as the password. Google shut Container Registry down on March 18, 2025; gcr.io addresses hosted on Artifact Registry keep working (Transition from Container Registry). For a <location>-docker.pkg.dev address, Google's Configure authentication to Artifact Registry for Docker uses the same user name, _json_key, with the key file as downloaded, or _json_key_base64 with the whole file base64-encoded.

image:
  name: us-central1-docker.pkg.dev/my-project/my-repo/build-env:1.0
  username: _json_key
  password: '$GAR_JSON_KEY'

The registry's logs may show a refused request before each successful pull. Atlassian's issue BCLOUD-23353 describes Pipelines trying without credentials first and then with them; it was closed in 2025 without a change, and the pull itself succeeds.

Bitbucket's own container registry

For an image in Bitbucket Packages (crg.apkg.io/<workspace>/...), BCLOUD-23970 shows an Atlassian account email as the username and an API token as the password. The issue itself is the error at the top of this page: in a workspace with IP Allowlist turned on, the pull fails with insufficient_scope. It was opened in January 2026 and is still open, and the only workaround it lists is turning the allowlist off.

Images built only for ARM

Cloud steps run on x86 unless the step asks for ARM. Atlassian's Step options has runtime: cloud: arch: arm, for builds on the Standard or Premium plan. An image built only for ARM does not run on x86: depending on how it was pushed, the pull stops with no match for platform in manifest, or it succeeds and the first command fails with exec format error. Build the image for both platforms, or run the step on ARM:

- step:
    runtime:
      cloud:
        arch: arm
    image: my-arm-image:1.0
    script:
      - ./build.sh

Many builds fail at once

When pulls fail in several repositories at the same time, look at Bitbucket's status page; in February 2024, self-hosted runners stopped with "Unable to pull image" during an incident listed there. Docker Hub's pull limit stops pulls too, with toomanyrequests ("You have reached your pull rate limit").

Bitbucket Pipelines in IntelliJ IDEA

Pipeline Inbox for Bitbucket Pipelines, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists the pipelines of all your Bitbucket Cloud repositories in an IDE tool window, with their steps, the failed step and the command it stopped at, and the step's log as Bitbucket writes it. The list, steps and logs are free; running, re-running and stopping pipelines are Pro (US$1.50 a month, with a 30-day trial).

Get it on JetBrains Marketplace

Atlassian, Bitbucket and Bitbucket Pipelines are trademarks of Atlassian; Docker is a trademark of Docker, Inc.; AWS is a trademark of Amazon.com, Inc. or its affiliates; Google Cloud is a trademark of Google LLC; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by Atlassian, Docker, Amazon, Google or JetBrains.

More: "Connection refused" to a service (MySQL, PostgreSQL, Redis) · "Not authorized to perform sts:AssumeRoleWithWebIdentity" (OIDC to AWS) · Test results not showing · A variable is empty · "Host key verification failed" (SSH) · "Cannot connect to the Docker daemon" · "authorization denied by plugin pipelines" (Docker) · "Container 'docker' exceeded memory limit." · Pipelines did not run after a push · "Container 'Build' exceeded memory limit." · "Exceeded build time limit of 120 minutes" · The cache is not used · "unexpected system error" · "command not found" · Submodules not cloned · "We couldn't clone the repository" · "No online runner available" · "No space left on device" · "Step exceeded processing limits" · The artifact is missing in the next step · The build passed before and fails now · Build setup takes too long · "You've run out of build minutes" · "Permission denied to update branch" · "You have reached your pull rate limit" (Docker Hub) · "There is an error in your bitbucket-pipelines.yml" · "This pipeline was paused" (deployments) · The scheduled pipeline did not run · Bitbucket Pipelines plugins for IntelliJ IDEA, compared · 日本語