Buildkite docker plugin image pull failed in CI

By Daniel Zoghalchali·Latchkey

The docker plugin pulls the configured image before running the step. A missing tag, unauthenticated private registry, or a registry rate limit makes the pull fail and the step never starts.

What this error means

A docker plugin step fails during setup with "manifest unknown", "pull access denied", or "toomanyrequests" for the configured image.

$ docker pull registry.example.com/app:latest
Error response from daemon: pull access denied for registry.example.com/app,
repository does not exist or may require 'docker login': denied: requested access to the resource is denied

Common causes

The tag is wrong or the registry needs auth

The image tag does not exist, or the private registry requires a docker login the agent never performed.

A registry rate limit throttled the pull

Anonymous or shared pulls from a public registry hit a rate limit, returning "toomanyrequests".

How to fix it

Authenticate before the docker plugin runs

1. Confirm the image and tag exist in the registry.
2. Log in to the registry in a step before the plugin, using credentials from a secret.
3. Re-run so the pull is authenticated.

steps:
  - command: "make test"
    commands:
      - "echo \"$REGISTRY_TOKEN\" | docker login registry.example.com -u ci --password-stdin"
    plugins:
      - docker#v5.11.0:
          image: "registry.example.com/app:1.4.2"

Avoid rate limits with authenticated pulls

Authenticated pulls have higher limits; log in even for public registries, or mirror hot images into a private registry.

How to prevent it

• Pin image tags that exist and authenticate to private registries.
• Use authenticated pulls to avoid anonymous rate limits.
• Mirror frequently pulled images to a registry you control.

Frequently asked questions

Related guides

References

• GitHub Actions documentation