Introduction

The error "Unsupported Docker v1 repository request" usually means a modern Docker client or registry path ended up speaking the old Registry API v1 protocol. Since current Docker tooling expects the v2 registry API, the fix is usually to make sure the client, registry, and any reverse proxy in front of it are all using the correct v2 endpoint and configuration.

Why The Error Happens

Docker registry v1 is obsolete. Modern clients expect the v2 API, which is exposed under /v2/.

If a private registry, load balancer, reverse proxy, or incorrect image reference sends the request down a v1 path, the registry rejects it with an error like this one.

A quick manual check is often useful:

curl -I https://registry.example.com/v2/

A healthy v2 registry usually responds with an authentication challenge or a success status that clearly shows the v2 endpoint exists.

Check The Image Reference And Login Flow

Make sure the image name and registry host are correct:

docker login registry.example.com
docker pull registry.example.com/my-team/my-image:latest

A typo in the hostname, a legacy proxy path, or a custom registry URL that omits the expected endpoint routing can all lead to confusing protocol errors.

If the registry requires authentication, perform docker login first and confirm credentials are valid before chasing lower-level protocol issues.

Reverse Proxies Are A Common Culprit

Many private registries sit behind Nginx, Apache, or another ingress layer. If that proxy is outdated or misconfigured, it may rewrite or block /v2/ requests incorrectly.

That is why the registry software itself may be fine while the external URL still fails. In practice, the proxy path, TLS termination, and upstream routing deserve as much attention as the registry container or service.

What To Fix

The practical fixes usually fall into one of these buckets:

• Upgrade or reconfigure the private registry so it serves the v2 API.
• Verify reverse-proxy rules forward /v2/ correctly.
• Make sure the Docker client is talking to the right registry host.
• Confirm authentication and certificates are correct.

If the registry really only supports v1, the real solution is migration rather than trying to force modern Docker clients backward.

A registry health check should usually validate both transport and protocol. Simply reaching the host over HTTPS is not enough if the reverse proxy still sends traffic to the wrong API path. Testing the registry endpoint directly is often the fastest way to separate protocol problems from bad image names or credentials.

Client configuration can contribute too. Very old Docker daemons, custom registry mirrors, or insecure-registry settings may direct traffic in surprising ways, especially in long-lived enterprise environments. If the server looks healthy but pulls still fail, inspect the local daemon configuration as part of the same debugging pass.

Common Pitfalls

One common mistake is treating the message as a generic authentication failure. Authentication may still matter, but the core issue is often protocol mismatch rather than bad credentials.

Another mistake is checking only the registry container and ignoring the reverse proxy or ingress layer in front of it. That front door often determines whether the v2 API is reachable.

A third issue is using a legacy or malformed image reference that points requests at the wrong host or path, making a healthy registry look broken.

Summary

• "Unsupported Docker v1 repository request" usually means a client or proxy reached an obsolete registry API path.
• Modern Docker tooling expects the registry v2 API, typically visible under /v2/.
• Check the registry URL, login flow, proxy configuration, and certificate setup together.
• If the registry only supports v1, the durable fix is to move to a v2-capable registry path or implementation.