GitLab CI "Preparation failed ... pull access denied" in CI

By Daniel Zoghalchali·Latchkey

The runner tried to pull the job's image: and the registry refused: "pull access denied" means the image is private and the runner has no credentials, or the repository name does not exist.

What this error means

The job fails during preparation with "ERROR: Preparation failed: Error response from daemon: pull access denied for X, repository does not exist or may require 'docker login'".

ERROR: Preparation failed: Error response from daemon: pull access denied for registry.example.com/app, repository does not exist or may require 'docker login'

Common causes

The image is private and the runner has no credentials

Pulling a private image needs registry auth; without DOCKER_AUTH_CONFIG or a login the daemon denies access.

A wrong or nonexistent image name

A typo in the repository or tag makes the registry report the repository does not exist, surfaced as access denied.

How to fix it

Provide registry credentials to the runner

1. Create a base64 DOCKER_AUTH_CONFIG for the registry.
2. Add it as a masked CI/CD variable so the runner authenticates pulls.
3. Re-run the job.

# masked CI/CD variable DOCKER_AUTH_CONFIG
{"auths":{"registry.example.com":{"auth":"<base64 user:token>"}}}

Correct the image reference

Confirm the repository and tag exist and are spelled correctly.

build:
  image: registry.example.com/app:1.2.3

How to prevent it

• Store registry auth in DOCKER_AUTH_CONFIG for private images.
• Verify image names and tags before referencing them.
• Use the project's built-in registry token where possible.

Frequently asked questions

Related guides

References

• GitHub Actions documentation