🚨 Docker Error Guide: 'unsupported media type' — Fix Registry Manifest Pulls

Overview

unsupported media type is a content-negotiation failure between the Docker client/daemon and a registry. Every manifest and layer served over the registry API carries a Content-Type (media type). When Docker receives a media type it does not recognize — because the manifest is an OCI or newer format an old daemon cannot parse, or because the endpoint is not actually a registry and returned HTML/JSON — it aborts with this error.

The literal error appears on pull or push:

Error response from daemon: unsupported media type application/vnd.oci.image.index.v1+json

A common variant names the manifest media type explicitly:

failed to pull and unpack image: unsupported media type application/vnd.docker.distribution.manifest.list.v2+json

Symptoms

• docker pull fails with unsupported media type naming a vnd.oci.* or vnd.docker.distribution.manifest.* type.
• An image pushed by a newer tool (buildx, kaniko, ko) cannot be pulled by an older Docker daemon.
• Pulling from a URL that is not a real registry (an artifact proxy, a raw object store, or an HTML error page) returns this error.
• A corporate proxy that rewrites or strips Accept/Content-Type headers breaks pulls that work off-network.

Common Root Causes

• OCI vs Docker manifest mismatch — the image was built/pushed as an OCI image index, but the consuming daemon is too old to understand OCI media types.
• Outdated Docker Engine — pre-20.10 daemons reject manifest formats that modern build tools emit by default.
• Endpoint is not a registry — the reference points at a plain HTTP endpoint or misconfigured proxy that returns text/html or application/json instead of a manifest.
• Proxy header rewriting — an inspecting proxy alters the Accept header so the registry serves a format the client did not ask for.
• Registry serving the wrong content type — a misconfigured or non-compliant registry returning an incorrect Content-Type.
• Build tool emitting a format the target registry rejects (rarer, on very old or restrictive registries).

Diagnostic Workflow

Check the Docker Engine version first — old daemons are the most common cause:

docker version --format '{{.Server.Version}}'

Inspect what media type the registry actually serves for the manifest:

TOKEN=... ; curl -sS -I \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.oci.image.index.v1+json" \
  https://<registry>/v2/<repo>/manifests/<tag> | grep -i content-type

Confirm the endpoint is a real registry (should answer the v2 API):

curl -sS -o /dev/null -w '%{http_code}\n' https://<registry>/v2/

Inspect the manifest media type with a tooling that speaks OCI:

docker buildx imagetools inspect <registry>/<repo>:<tag>

Look for proxy interference in the daemon environment:

systemctl show --property=Environment docker | tr ' ' '\n' | grep -i proxy

Example Root Cause Analysis

A production host running Docker 19.03 failed to pull an image that a CI pipeline had just pushed with buildx:

unsupported media type application/vnd.oci.image.index.v1+json

docker buildx imagetools inspect from a modern workstation showed the image was published as an OCI image index, which the 19.03 daemon on the host could not parse. The registry and network were fine; the consuming engine was simply too old for the OCI media type.

The fix had two paths: short-term, the CI pipeline re-published the image with --provenance=false --sbom=false and Docker manifest media types (docker buildx build --output type=image,oci-mediatypes=false) so the old daemon could consume it; long-term, the host’s Docker Engine was upgraded to a current release that understands OCI formats natively. After the upgrade the OCI index pulled without any build-side workaround.

Prevention Best Practices

• Keep Docker Engine current across all consuming hosts so OCI and modern manifest formats are always understood.
• Standardize manifest format in CI to match the oldest consumer, or upgrade consumers so you can use OCI defaults.
• Point references at real registries; never pull from artifact proxies or object-store URLs that do not implement the registry v2 API.
• Exempt registries from header-rewriting proxies so Accept/Content-Type negotiation is not corrupted.
• Verify with buildx imagetools inspect in CI to confirm the published media type before rollout.
• Test pulls on the lowest-version host in your fleet as part of release validation.

Quick Command Reference

docker version --format '{{.Server.Version}}'    # is the daemon too old?
docker buildx imagetools inspect <ref>           # see actual manifest media type
curl -sS -o /dev/null -w '%{http_code}\n' https://<registry>/v2/   # real registry?
curl -sSI -H 'Accept: application/vnd.oci.image.index.v1+json' \
  https://<registry>/v2/<repo>/manifests/<tag> | grep -i content-type
docker buildx build --output type=image,oci-mediatypes=false -t <ref> --push .

Conclusion

unsupported media type is failed content negotiation: Docker got a manifest format it cannot parse or a response from something that is not a registry. The usual culprit is an OCI image index reaching an outdated daemon — upgrade the engine, or emit Docker media types in CI for old consumers. Always confirm the endpoint is a real v2 registry and that proxies are not rewriting headers. For unknown-manifest failures, see the manifest unknown guide and the full Docker guides.