Maaz Zindani

Loading the index…

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

docker pull or push fails against a private registry without valid HTTPS

Errortls: oversized record received with length 20527

Short 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.

  • Applies to Docker Engine 27, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 info
  2. 2Match what you see, then jump to its fix

    1. 1tls: oversized record received with length ... on pull, push or loginThe registry serves plain HTTPFix
    2. 2pull 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. 3You added insecure-registries but docker info does not list itdaemon.json is wrong, so the setting never appliesFix

What does the error look like?

  • tls: oversized record received with length 20527
  • Error 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 docker

3Verify

docker info lists the registry under insecure registries and a pull works.

docker info
docker pull registry.example.com:5000/my-image:latest

Confirmed by distribution.github.io

Did this fix it?

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.crt

3Verify

Pull again from the registry.

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

Confirmed by docs.docker.com

Did this fix it?

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.json

2Fix

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

Did this fix it?

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

Next step

Want this handled for good?

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