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

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'".

GitLab Runner

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

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

CI/CD variable

# 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.

.gitlab-ci.yml

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.