Docker "error parsing HTTP 404 response body" - Fix Wrong Registry Endpoint

Docker expected a registry v2 API response but got a 404 whose body was not valid registry JSON - usually because the URL points at something that is not a registry, or at the wrong path.

What this error means

A pull or push fails with error parsing HTTP 404 response body, often quoting an HTML snippet. The host responded, but with a generic 404 page, not the /v2/ registry API the daemon expected.

docker pull/push output

error parsing HTTP 404 response body: invalid character '<' looking for
beginning of value: "<html><head><title>404 Not Found</title>..."

Common causes

The host is not a registry (or wrong port/path)

The reference points at a web server, a load balancer default page, or the wrong port, so /v2/ returns an HTML 404 instead of a registry response.

A proxy or gateway intercepts the request

A reverse proxy that does not forward the /v2/ registry path returns its own 404 page, which Docker cannot parse as a v2 response.

The registry path/namespace is wrong

A malformed repository path under an otherwise-valid registry can resolve to a 404 served as HTML by the front end.

How to fix it

Verify the registry v2 endpoint directly

Curl the /v2/ API path - a real registry returns JSON (often a 401 challenge), not an HTML 404.

Terminal

curl -i https://registry.example.com/v2/
# a registry replies with JSON / a Www-Authenticate header, not <html>

Fix the host, port, and repository path

Confirm the registry host and port actually serve the Docker Registry HTTP API v2.
Make sure any proxy in front forwards /v2/ to the registry unchanged.
Correct the repository path/namespace in the image reference.

How to prevent it

Point image references at the real registry host/port, not a web front end.
Configure proxies to pass through the /v2/ registry API.
Smoke-test GET /v2/ when standing up a new registry endpoint.