CircleCI "Cannot pull image" / Authentication Required

By Daniel Zoghalchali·Latchkey

The docker executor could not pull an image because it sent no credentials, or the wrong ones. The registry rejects the pull, so the job cannot start its container.

What this error means

The job fails during "Spin up environment" / image pull with "unauthorized: authentication required" or "pull access denied". Public images work; the private one is rejected.

Error response from daemon: pull access denied for myorg/app,
repository does not exist or may require 'docker login':
denied: requested access to the resource is denied

Common causes

No auth block on the image

The docker: image entry has no auth:, so CircleCI pulls anonymously and the private registry denies it.

Wrong, expired, or unattached credentials

The username/token env vars are missing, misspelled, or live in a context that was never attached to the job.

Docker Hub anonymous rate limit

Even public images hit Docker Hub's anonymous pull limit and return an auth-style error; authenticating raises the limit.

How to fix it

Add auth to the private image

jobs:
  build:
    docker:
      - image: myorg/app:latest
        auth:
          username: ${DOCKERHUB_USER}
          password: ${DOCKERHUB_PASS}
    steps: [checkout, { run: ./build.sh }]

Provide credentials via a context

1. Store the registry user/token in an org context.
2. Attach that context to the job in the workflow.
3. Authenticate Docker Hub pulls to dodge anonymous rate limits.

How to prevent it

• Always add an auth: block for private registry images.
• Keep registry credentials in a shared context, scoped to pull.
• Authenticate Docker Hub pulls to avoid anonymous rate limits.

Frequently asked questions

Related guides

References

• GitHub Actions documentation