Docker Core
The TLS certificate presented by the registry chains to no trusted authority.
x509-unknown-authorityReviewed for reference consistency: August 11, 2026
The TLS certificate presented by the registry chains to no trusted authority.
What x509-unknown-authority Means
The x509-unknown-authority error on the Docker Core indicates the tls certificate presented by the registry chains to no trusted authority.. This typically occurs due to the registry's certificate is self-signed and not installed into the trust store.
The daemon validates registry connections against the host trust store plus certificates under the Docker certificates directory. Self-signed or corporate-intercepted registries present a chain the client cannot verify, and the TLS layer rejects the handshake with the unknown-authority wording.
How to fix x509-unknown-authority
General informational guidance, not professional advice. Commands can affect your system or data — back up first and proceed at your own risk. FixerCode is an independent reference, not affiliated with any vendor mentioned.
Show the chain the registry actually serves
Connecting with openssl prints the served certificate chain and its issuer, exposing missing intermediates directly.
openssl s_client -connect <registry-host>:443 -showcerts </dev/nullList the per-registry trust directory
Certificates Docker trusts beyond the system store live under the certs.d path named after the registry host.
ls -R /etc/docker/certs.d
Technical Background
This failure happens inside the TLS handshake, before any registry protocol runs, so it produces no manifest or auth messages: the connection itself is refused.
Docker extends the system trust model with a per-registry certificates directory, which is how private registries gain trust without weakening verification globally. Disabling verification instead moves the registry into the insecure-registry category, a trade the daemon treats as an explicit administrative decision.
Common Causes
- The registry's certificate is self-signed and not installed into the trust store
- The served chain omits the intermediate certificate
- A TLS-intercepting proxy replaced the original certificate
- The certificate directory for that registry host holds a stale copy
Typical Scenarios
- Pulling from an internal registry that uses a self-signed certificate
- A corporate proxy re-signing TLS traffic with its own root certificate
- A registry deployed without its intermediate certificate in the served chain
What to Know
The error text names the failing step as certificate verification, which separates it from the authentication and rate-limit families; the registry host in the message identifies which trust directory matters.
Frequently Asked Questions
Common questions about Docker x509-unknown-authority error
curl and the daemon may consult different trust stores; the daemon also reads its own per-registry certificate directory, so one tool can verify while the other cannot.
It exists as a documented option with real risk: an insecure-registry entry disables verification for that host, trading certificate checking for availability.
Related Error Codes
The registry refused the pull because the repository is private or unknown.
The registry answered with a 401 asking the client to authenticate first.
The daemon returned a structured error response carrying the failure detail.
Related Errors From Other Categories
Similar error codes documented across different platforms and systems