GitLab CI "failed to pull image" / "no basic auth credentials"

The runner could not pull the container image for your job (or a service). The tag is wrong, the registry needs credentials the job does not have, or the pull was rate-limited.

What this error means

The job fails during preparation while pulling the image: - "manifest unknown", "not found", "no basic auth credentials", or "toomanyrequests". Your script never runs because there is no container.

Job log

ERROR: Job failed: failed to pull image "registry.example.com/app:latst"
with specified policies [always]: Error response from daemon:
manifest for registry.example.com/app:latst not found: manifest unknown

Common causes

Wrong image name or tag

A typo in the repository or tag (latst for latest), or a tag that was never pushed, yields "manifest unknown"/"not found".

Private registry without credentials

Pulling from a private registry needs auth. Without DOCKER_AUTH_CONFIG or a CI/CD job-token login, the runner gets "no basic auth credentials".

Registry rate limit

Anonymous Docker Hub pulls are rate-limited ("toomanyrequests"). Under load the pull is throttled and fails transiently.

How to fix it

Use a correct, existing tag

Pin to a tag you know exists in the registry; verify with a manual pull.

.gitlab-ci.yml

image: registry.example.com/app:1.4.2

Provide registry credentials

For the GitLab registry, log in with the CI job token; for others, set DOCKER_AUTH_CONFIG.

Job script

# GitLab Container Registry
docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"

How to prevent it

Pin image tags and verify they exist before merging.
Configure DOCKER_AUTH_CONFIG for private registries.
Use a pull-through mirror or authenticated pulls to dodge rate limits.