x509: certificate signed by unknown authority (pulling from a private registry)

TL;DR: Give the daemon the registry CA certificate: copy the CA cert to /etc/docker/certs.d/[registry-host]/ca.crt and restart docker. The daemon validates registry TLS against the host trust store plus per-registry cert dirs; a private CA is unknown until you install it there.

The error

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

Fix it

1. Get the CA certificate (PEM) from your registry admin.
2. Place it where the daemon looks:

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 Expected: file in place, owned by root.

1. Restart the daemon:

sudo systemctl restart docker

1. Retry the pull:

docker pull registry.example.com:5000/myimage:tag Expected: succeeds.

When this applies

• Self-hosted registries with internal CA or self-signed certs
• Corporate MITM proxies re-signing registry traffic

When this does NOT apply

• Public registries (their certs chain to public roots; check your clock/proxy instead)
• "http: server gave HTTP response to HTTPS client" (plain HTTP registry, different fix)

Versions

All Docker versions.

Why it happens

The daemon does full TLS verification on registry connections. Internal CAs are not in the default trust bundle, so verification fails before any HTTP happens.

Edge cases

• The directory name must match the registry host AND port exactly (YOUR_REGISTRY_HOST:5000).
• Docker Desktop: put certs in the VM via Settings, or mount; /etc/docker/certs.d on the Mac host is not read by the VM daemon.
• Expired certs give a different x509 message ('certificate has expired'); renew instead of reinstalling CA.
• As a last resort, "insecure-registries" in daemon.json skips verification, but it disables TLS checks entirely; prefer installing the CA.