Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker build stops while loading metadata for the base image

ErrorERROR [internal] load metadata for docker.io/library/node:22

Short answer

The build could not look up the base image from FROM. Two things cause most of it: a credsStore entry in ~/.docker/config.json that names a helper which is not on PATH, and a daemon that needs a proxy to reach the registry. Read the full error line after the metadata message to tell them apart.

  • Applies to Docker Engine 28, Docker Desktop 4, BuildKit
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the Docker client config and look for credsStore or credHelpers, then try a plain pull to separate a registry problem from a build problem.

    cat ~/.docker/config.json
    docker pull hello-world
  2. 2Match what you see, then jump to its fix

    1. 1config.json has a credsStore or credHelpers entry, and the helper program is not found when you run itThe credential helper in config.json is not on PATHFix
    2. 2docker pull also hangs or times out, and the machine sits behind a corporate proxyThe daemon needs a proxy to reach the registryFix

What does the error look like?

  • ERROR [internal] load metadata for docker.io/library/node:22

Cause 1 of 2

The credential helper in config.json is not on PATH

1Check

The value of credsStore is the suffix of a helper program, and Docker requires that program to be on the client's PATH.

grep -n -E "credsStore|credHelpers" ~/.docker/config.json
which docker-credential-desktop docker-credential-osxkeychain

2Fix

Put the helper's folder on PATH, or remove the credsStore line if you do not need a store. If you are logged in, run docker logout first, then log in again.

docker logout
sudoedit ~/.docker/config.json   # delete the "credsStore" line
docker login

3Verify

A pull works again.

docker pull hello-world

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 2

The daemon needs a proxy to reach the registry

1Check

The daemon uses its own proxy settings to reach Docker Hub and other registries. Show what systemd gave it.

sudo systemctl show --property=Environment docker

2Fix

Set the proxy in daemon.json, or in a systemd drop-in. On Docker Desktop, set it in the app settings; proxies in daemon.json are ignored there.

{
  "proxies": {
    "http-proxy": "http://proxy.example.com:3128",
    "https-proxy": "http://proxy.example.com:3128",
    "no-proxy": "localhost,127.0.0.1"
  }
}

3Verify

Restart the daemon and pull again.

sudo systemctl restart docker
docker pull hello-world

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Keep credential helpers installed and on PATH, or do not configure a store.
  • Record proxy settings in the machine setup, not as a one-off terminal export.
  • Pull a small image with docker pull as the first test when builds fail early.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.