docker pull or push fails against a private registry without valid HTTPS
tls: oversized record received with length 20527Short answer
Docker treats every registry as secure except local ones. A registry on plain HTTP, or with a certificate from a CA the daemon does not trust, is refused. Either trust the CA in /etc/docker/certs.d, or list the registry in insecure-registries in /etc/docker/daemon.json and reload.
Fix it fast
1Find out which cause you have
Find out whether the registry speaks HTTP or HTTPS, and see what the daemon already allows.
curl -sI http://registry.example.com:5000/v2/ docker info2Match what you see, then jump to its fix
- 1
tls: oversized record received with length ... on pull, push or loginThe registry serves plain HTTPFix - 2
pull fails on a self-signed or internal-CA certificate, while curl -k worksThe registry uses TLS with a CA the daemon does not trustFix - 3
You added insecure-registries but docker info does not list itdaemon.json is wrong, so the setting never appliesFix
- 1
What does the error look like?
tls: oversized record received with length 20527Error response from daemon: v1 ping attempt failed with error
Cause 1 of 3
The registry serves plain HTTP
1Check
The client opened a TLS handshake and got an HTTP answer back. The curl over http succeeds while https fails.
curl -sI http://registry.example.com:5000/v2/
curl -sI https://registry.example.com:5000/v2/2Fix
Best fix: put TLS on the registry with a certificate from a known CA. For a test box, add the host and port to insecure-registries on every Docker host that uses it, then restart Docker.
# /etc/docker/daemon.json
{
"insecure-registries": ["registry.example.com:5000"]
}
sudo systemctl restart docker3Verify
docker info lists the registry under insecure registries and a pull works.
docker info
docker pull registry.example.com:5000/my-image:latestConfirmed by distribution.github.io
Cause 2 of 3
The registry uses TLS with a CA the daemon does not trust
1Check
Docker also calls a registry insecure when its CA certificate is missing from /etc/docker/certs.d/<registry>/. The directory is named after the registry host, with the port if there is one.
ls -l /etc/docker/certs.d/registry.example.com:5000/2Fix
Put the CA certificate in PEM format in that directory, named with a .crt extension. This keeps verification on and is safer than insecure-registries.
sudo mkdir -p /etc/docker/certs.d/registry.example.com:5000
sudo cp ca.crt /etc/docker/certs.d/registry.example.com:5000/ca.crt3Verify
Pull again from the registry.
docker pull registry.example.com:5000/my-image:latestConfirmed by docs.docker.com
Cause 3 of 3
daemon.json is wrong, so the setting never applies
1Check
The registry must be written as host:port, or as a CIDR range such as 10.1.0.0/16. A syntax error, or the same option set both in the file and as a dockerd flag, stops it from applying. Validate the file without starting the daemon.
sudo dockerd --validate --config-file=/etc/docker/daemon.json2Fix
Fix the entry the validator names. On Linux, insecure-registries can also be reloaded without a restart.
sudo kill -SIGHUP $(pidof dockerd)3Verify
The registry now shows in docker info under insecure registries.
docker info | grep -A5 -i 'insecure registries'Confirmed by docs.docker.com
How do I stop it coming back?
- Give the registry a real certificate. Plain HTTP exposes images and cannot use basic authentication.
- Use certs.d with the internal CA instead of insecure-registries.
- Do not rely on 127.0.0.0/8 being insecure by default; the docs say that may change.
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
Servers
docker pull fails with net/http: TLS handshake timeout from the registry
net/http: TLS handshake timeout
The Docker daemon, not your shell, opens the connection to the registry, and its TLS handshake did not finish in time.
2 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fix