Introduction Docker image pull failures block deployments, container starts, and CI/CD pipelines. The most common errors are "unauthorized: authentication required" and "manifest unknown" - indicating authentication issues or missing image tags.
Symptoms - `docker pull` returns: "unauthorized: authentication required" - Error: "Error response from daemon: pull access denied for <image>, repository does not exist" - Kubernetes pods show: "Failed to pull image: rpc error: code = Unknown desc = failed to pull" - CI/CD pipeline fails at the image build/deploy step
Common Causes - Docker not logged in to private registry (docker login expired) - Image tag does not exist in the registry - Registry credentials not passed to Docker daemon (docker-compose, k8s) - Docker Hub rate limit exceeded (anonymous: 100 pulls/6hr) - Self-signed certificate not trusted for private registry
Step-by-Step Fix 1. **Check authentication status**: ```bash cat ~/.docker/config.json | grep -A2 "auths" docker pull myregistry.example.com/my-app:v1.0.0 ```
- 1.Login to the registry:
- 2.```bash
- 3.docker login myregistry.example.com -u myuser -p mypassword
- 4.# Or with credential helper
- 5.echo "mypassword" | docker login myregistry.example.com -u myuser --password-stdin
- 6.
` - 7.Verify image tag exists:
- 8.```bash
- 9.# Docker Hub API
- 10.curl -s "https://hub.docker.com/v2/repositories/library/nginx/tags/" | jq '.results[].name'
- 11.# Private registry API
- 12.curl -s https://myregistry.example.com/v2/my-app/tags/list -u user:pass
- 13.
` - 14.Configure imagePullSecrets for Kubernetes:
- 15.```bash
- 16.kubectl create secret docker-registry regcred \
- 17.--docker-server=myregistry.example.com \
- 18.--docker-username=myuser \
- 19.--docker-password=mypass
- 20.
` - 21.Then reference in pod spec:
imagePullSecrets: [{name: regcred}]