Docker "x509: certificate signed by unknown authority" (private registry) in CI

The daemon verifies a registry's TLS certificate against its trusted CAs. A private registry fronted by an internal CA whose root the daemon does not trust fails with x509: certificate signed by unknown authority. The same message can also appear transiently when a TLS dial is interrupted before the handshake completes.

What this error means

A docker pull/push to a private registry fails with x509: certificate signed by unknown authority. The registry uses a cert from an untrusted CA.

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

Common causes

The registry CA is not in the trust store

An internal CA root not installed where the daemon looks makes the cert untrusted.

Daemon cert directory not configured

The daemon expects the CA under /etc/docker/certs.d/<registry>/ca.crt; without it the cert is rejected.

A transient TLS dial interruption

A momentary network drop during the TLS handshake can surface as a verification error before retrying.

How to fix it

Install the registry CA where the daemon trusts it

1. Place the CA cert under the per-registry certs.d path.
2. Restart the daemon and retry the pull/push.

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

1. Install the CA at the OS level so all clients trust it.

sudo cp ca.crt /usr/local/share/ca-certificates/registry-internal.crt
sudo update-ca-certificates

How to prevent it

• Distribute the internal CA to all runner hosts.
• Use certs.d per-registry CA files for the daemon.
• Avoid disabling TLS verification as a workaround.

Related guides