Docker "x509: certificate signed by unknown authority" - Fix Registry TLS

By Daniel Zoghalchali·Latchkey

The Docker daemon could not verify the registry’s TLS certificate because the signing CA is not in the runner’s trust store. Common with self-hosted or corporate registries using a private CA.

What this error means

A docker pull/push against a private registry fails during the TLS handshake with x509: certificate signed by unknown authority. Public registries work; only the private host fails - and it fails the same way every run until trust is fixed.

docker pull/push output

Error response from daemon: Get "https://registry.internal:5000/v2/":
x509: certificate signed by unknown authority

Common causes

Registry uses a self-signed or private-CA certificate

A self-hosted registry signed by an internal CA presents a certificate the runner has never seen. Without the CA in the trust store, verification fails.

The CA bundle is missing on a minimal runner

A slim runner image without up-to-date ca-certificates may not trust even a publicly-signed registry, surfacing the same x509 error.

How to fix it

Install the registry’s CA for the daemon

Place the CA certificate where the Docker daemon looks for per-registry certs, then restart the daemon.

Terminal

sudo mkdir -p /etc/docker/certs.d/registry.internal:5000
sudo cp ca.crt /etc/docker/certs.d/registry.internal:5000/ca.crt
sudo systemctl restart docker

Add the CA to the system trust store

For tools beyond the daemon, trust the CA system-wide.

Terminal

sudo cp corporate-root.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

How to prevent it

Bake the private registry’s CA into the runner image or trust store.
Keep ca-certificates current on runner images.
Prefer per-registry certs.d trust over a global insecure-registry setting.

Frequently asked questions

What causes ""x509: certificate signed by unknown authority""?