Skip to main content
RunBook Academy

← All break/fix scenarios in Docker & Containers

intermediateNetworking~15 min

Break/Fix 3: Container cannot pull image from registry

Reported symptoms

  • ●docker pull fails with "unauthorized: authentication required"
  • ●docker pull fails with "dial tcp: lookup registry.example.com: no such host"
  • ●docker pull fails with TLS errors

Evidence

  • · Error message from docker pull command
  • · curl output to the registry URL
  • · docker login attempts and outputs
Diagnosis and resolutionclick to reveal

Root cause

The most common cause is missing or expired authentication credentials. The second most common is DNS resolution failure. The third is TLS verification failure due to misconfigured certificates.

Remediation

Run docker login with valid credentials. Verify DNS resolves the registry hostname. Check that the registry's certificate is valid and trusted by the host's CA bundle. Use docker pull with explicit username and password if needed.

Verification

docker pull succeeds. The image is in the local cache. Login succeeds. DNS resolves the registry hostname.

Prevention

Set up automated credential refresh. Use credential helpers configured in daemon.json. Monitor registry availability.

Reported symptoms

  • docker pull myorg/myapp:1.0.0 fails.
  • Error message indicates authentication, DNS, or TLS issue.

Evidence provided

$ docker pull registry.example.com/myorg/myapp:1.0.0
# Error: unauthorized: authentication required

or

# Error: dial tcp: lookup registry.example.com on 8.8.8.8:53: no such host

Resolution path

  1. Try docker login.
  2. docker login registry.example.com
  3. Provide valid credentials. If anonymous access is allowed, skip this step.
  4. Verify DNS.
  5. nslookup registry.example.com
  6. dig registry.example.com
  7. If DNS fails, check /etc/resolv.conf and DNS server reachability.
  8. Verify TLS.
  9. curl -vI https://registry.example.com/v2/
  10. Check the certificate is valid and trusted by the host CA bundle.
  11. If using a private registry with self-signed certs.
  12. Configure the daemon to trust the cert:
  13. mkdir -p /etc/docker/certs.d/registry.example.com
  14. cp ca.crt /etc/docker/certs.d/registry.example.com/ca.crt
  15. Restart the daemon: systemctl restart docker.
  16. For rate-limited Docker Hub.
  17. Authenticate: docker login (with Docker Hub account).
  18. Or use a pull-through cache mirror.

Verification

  1. docker pull succeeds.
  2. Image is in the local cache. docker images | grep myorg/myapp.
  3. Login works without re-auth. docker login registry.example.com (already authenticated).