GitLab CI "failed to pull image" / "no basic auth credentials"
By Daniel Zoghalchali·Latchkey
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.
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.
Frequently asked questions
What causes ""failed to pull image""?
A typo in the repository or tag (latst for latest), or a tag that was never pushed, yields "manifest unknown"/"not found".
How do I fix "failed to pull image"?
Pin to a tag you know exists in the registry; verify with a manual pull.
Can Latchkey fix this automatically?
Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.
