Container Image Pull Failed: Step-by-Step Fix

So your docker pull failed. The error says something like pull access denied or manifest not found. This happens a lot on Ubuntu 22.04 with Docker 24.x, or when you're pulling from a private registry like Harbor or ECR.

What's actually happening here is that Docker can't get the image layers from the registry. The cause is usually one of three things: your credentials are wrong, your DNS can't resolve the registry hostname, or the registry itself is misconfigured. Let's fix it in order.

Step 1: Check Your Login (30 seconds)

If you get pull access denied for ..., Docker doesn't know who you are. Try this:

docker logout
# then
docker login

If you're using Docker Hub, you might be logged into a different account. Or maybe your token expired. After re-login, try the pull again.

The reason this works: Docker stores credentials in ~/.docker/config.json. If that file is corrupt or missing, it won't send the auth header. A fresh docker login rewrites it.

If you're on a private registry like myregistry.io:5000, include the full address:

docker login myregistry.io:5000 -u admin -p mypass

Still failing? Move on.

Step 2: Check DNS and Network (5 minutes)

If the error says dial tcp: lookup ... no such host, Docker can't resolve the registry name. This is common on corporate networks or when using a VPN.

nslookup registry-1.docker.io
# or for your private registry:
nslookup myregistry.io

If that returns server can't find ..., your DNS settings are broken. On Ubuntu with systemd-resolved, check /etc/resolv.conf. You might need to set Docker's DNS manually.

Edit /etc/docker/daemon.json (create it if missing):

{
  "dns": ["8.8.8.8", "1.1.1.1"]
}

Then restart Docker:

sudo systemctl restart docker

What's happening here is that Docker ignores your system's DNS by default and uses its own resolver. Setting explicit DNS servers bypasses any local DNS issues.

Also check if a firewall is blocking port 443. Run curl -v https://registry-1.docker.io/v2/ — if you get a timeout or connection refused, that's a firewall problem.

Step 3: Check Registry Configuration (15+ minutes)

If steps 1 and 2 didn't help, the issue is likely on the registry side. This applies to private registries, especially self-hosted ones.

3a: Verify the Image Name and Tag

The error manifest for ... not found means the tag doesn't exist. For example, docker pull alpine:3.19 works, but alpine:3.20 might not if you mistyped. Check the exact tag on Docker Hub or your registry's web UI.

Private registries often have tags like v1.0.0 but you wrote latest. If the image was pushed without a latest tag, Docker won't find anything.

3b: Check Registry Certificates

If your registry uses a self-signed certificate, Docker will reject it. The error is usually certificate signed by unknown authority. Copy the CA cert to /etc/docker/certs.d/<registry-host>:<port>/ca.crt.

Example for myregistry.io:5000:

sudo mkdir -p /etc/docker/certs.d/myregistry.io:5000
sudo cp my-ca.pem /etc/docker/certs.d/myregistry.io:5000/ca.crt
sudo systemctl restart docker

The reason this works: Docker looks in that directory for trusted CAs when connecting to a registry. If the cert isn't there, it refuses to connect.

3c: Registry HTTP (Insecure) Mode

For testing only — never in production — you can allow HTTP. Add to /etc/docker/daemon.json:

{
  "insecure-registries": ["myregistry.io:5000"]
}

This is a hack. Only use it if you control the registry and can't get HTTPS working.

3d: Check Registry Backend Health

If the registry itself is down, no fix on your side helps. Ping the registry host. Try curl -I https://myregistry.io/v2/ — you should get a 200 or 401. If you get a 502 or timeout, tell your ops team.

When to Give Up and Switch Registries

If you've done all this and it still fails, the issue might be Docker's built-in pulling mechanism. Try pulling with podman or nerdctl as a test. If those work, your Docker installation is broken. Reinstall Docker completely:

sudo apt purge docker-ce docker-ce-cli containerd.io
sudo rm -rf /var/lib/docker
sudo apt install docker-ce

That nukes everything and starts clean. It fixes corruption in the Docker overlay filesystem or config.

Most people stop at step 1. If you're reading this far, you probably have a private registry with a self-signed cert. Keep a copy of that CA file in a safe place — you'll need it again.