Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

Docker "x509: certificate signed by unknown authority" on pull or login to a private registry

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

When docker pull or docker login against your own registry fails with "x509: certificate signed by unknown authority", the Docker host could not build a trusted path from the registry's certificate to a certificate authority (CA) it knows. Usually the registry uses an internal CA the host has never been given, or the server does not send its intermediate certificate. Docker's per-registry CA directory fixes the first case and is limited to that registry.

What the error means

The wording comes from the source code of Go's crypto/x509 package (release tag go1.26.0), not from a Docker page: "x509: certificate signed by unknown authority". The source can append a format with variable parts, " (possibly because of %q while trying to verify candidate authority certificate %q)", where each %q is a quoted detail filled in at run time.

Docker treats a private registry as secure or insecure. The dockerd reference says a secure registry "uses TLS and a copy of its CA certificate is placed on the Docker host at /etc/docker/certs.d/myregistry:5000/ca.crt". An insecure registry "is either not using TLS ... or is using TLS with a CA certificate not known by the Docker daemon", which includes the case where the certificate was not found in that directory or verification failed. By default, Docker assumes all registries are secure, except local ones.

Other certificate faults have different messages. The Go source also defines x509: certificate has expired or is not yet valid: <detail> and x509: certificate is valid for <names>, not <host>, in which the detail, the names and the host vary with the certificate. Those point at the date or the name, not the CA, and need a different fix.

Likely causes

Cause What you see How to confirm
Registry certificate signed by an internal or self-signed CA the host lacks The error on every Docker host that lacks the CA openssl s_client with -verify_return_error fails; the same command with -CAfile and the CA file succeeds
Server sends only its own certificate, not the intermediate Other clients with the same trust store also fail openssl s_client -showcerts lists one certificate where two or more are expected
A TLS-inspecting proxy replaces the registry's certificate The certificate's issuer is the proxy's CA -showcerts shows an issuer you do not recognise
CA is in certs.d, but the directory name or file name is wrong The error persists after you "added" the CA The directory must match the registry name and port exactly, and the file must end in .crt

Prove the cause before changing anything

All of these only read from the registry. Replace registry.example.com:5000 with your registry.

  1. Reproduce and keep the full message:
docker pull registry.example.com:5000/app:1.0
  1. List what the server sends. The OpenSSL manual says -showcerts "Displays the server certificate list as sent by the server: it only consists of certificates the server has sent (in the order the server has sent them). It is not a verified chain." The -servername option sets the name the server sees.
openssl s_client -connect registry.example.com:5000 -servername registry.example.com -showcerts

The command waits for input once connected. End it from the keyboard when you have the output. Count the certificates and read the subject and issuer printed for each. A good result is the registry's certificate followed by the intermediate. A bad result is only the registry's certificate, or an issuer that is a proxy.

  1. Test verification the way a strict client does. The manual says -verify_return_error returns verification errors, which "will typically abort the handshake with a fatal error". First without any extra CA, then with the internal CA file:
openssl s_client -connect registry.example.com:5000 -servername registry.example.com -verify_return_error
openssl s_client -connect registry.example.com:5000 -servername registry.example.com -CAfile /root/internal-ca.crt -verify_return_error

If the first fails and the second connects, the cause is a CA the host does not trust. If both fail, the server's chain is incomplete or the certificate is wrong.

  1. Check what Docker already has:
ls -la /etc/docker/certs.d

Example (illustrative): web01 pulls registry.example.com:5000/app:1.0 from a registry that uses a certificate signed by "Example Internal CA". docker pull prints the x509 error. -showcerts lists two certificates, so the chain is complete. The first s_client command fails verification and the second, with -CAfile /root/internal-ca.crt, connects. ls /etc/docker/certs.d is empty. The fix is /etc/docker/certs.d/registry.example.com:5000/ca.crt. The directory name includes the port because the pull address does.

Fix

Give Docker the CA for this registry only

The certificates page says a custom certificate is configured "by creating a directory under the daemon's certificate root using the same name as the registry's hostname". On native Linux the root is /etc/docker/certs.d/. "All *.crt files are added to this directory as CA roots." If the registry is reached without a port, leave the port out of the directory name. On Linux these roots are merged with the system defaults. Name the CA file ca.crt, as the page's example does.

First list the certificate directory and keep the output, which shows what exists before the change:

ls -laR /etc/docker/certs.d

If the listing already shows a ca.crt under registry.example.com:5000, stop here. The next cp would replace it, and the undo steps below only remove a file you added. Work out why that CA is not accepted instead.

Risk: the next commands make this host trust the CA in the file for registry.example.com:5000. If the file is the wrong CA, whoever holds that CA's key can impersonate the registry to this host.

Create the directory and copy the CA certificate in as ca.crt, then try the pull:

mkdir -p /etc/docker/certs.d/registry.example.com:5000
cp /root/internal-ca.crt /etc/docker/certs.d/registry.example.com:5000/ca.crt
docker pull registry.example.com:5000/app:1.0

The certificates page does not say whether the Docker daemon must be restarted after this, so try the pull first.

To undo it: remove the file you added, using its full name:

rm /etc/docker/certs.d/registry.example.com:5000/ca.crt

Then, only if the saved listing showed that the directory did not exist before, remove the empty directory:

rmdir /etc/docker/certs.d/registry.example.com:5000

Make the registry send its full chain

If -showcerts showed only the registry's certificate, the fix is on the registry server. The Distribution deployment page says that when an issuer supplies an intermediate certificate, you "must concatenate your certificate with the intermediate certificate to form a certificate bundle", and gives this command, run where domain.crt and intermediate-certificates.pem are, with certs/domain.crt as the file the registry uses.

First save the file the registry serves:

cp -p certs/domain.crt certs/domain.crt.2026-11-22

Disruptive step: the next command replaces the certificate file the registry serves, and the reload that follows it restarts or reloads the registry, which can interrupt every client of this registry. A wrong bundle breaks TLS for all of them.

cat domain.crt intermediate-certificates.pem > certs/domain.crt

The page does not say how a running registry loads a changed file, so follow your deployment's own procedure to reload it. Then repeat the -showcerts check.

To undo it: first check that the saved copy exists, then put it back under its original name, and reload the registry the same way as before:

ls -l certs/domain.crt.2026-11-22
cp -p certs/domain.crt.2026-11-22 certs/domain.crt

Add the CA to the host's system trust (Debian and Ubuntu)

Use this when other programs on the host need the same CA. The Debian manual says update-ca-certificates includes "all certificates with a .crt extension found below /usr/local/share/ca-certificates".

First list that directory and keep the output:

ls -la /usr/local/share/ca-certificates

If the listing already shows internal-ca.crt, stop here. The next cp would replace it, and the undo steps below only remove a file you added. Use a different file name for your CA instead, and use that name in the commands that follow.

Risk: the next commands make every program on this host that uses the system trust store accept certificates issued by this CA, not only Docker.

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

To undo it: remove the file you added, then rebuild the store. The manual describes --fresh as removing the symlinks in /etc/ssl/certs:

rm /usr/local/share/ca-certificates/internal-ca.crt
update-ca-certificates --fresh

A TLS-inspecting proxy

The dockerd reference says that behind an HTTPS proxy "the proxy's certificates replace Docker Hub's certificates" and that the proxy's CA certificate, from your network administrator, must be added to the host. The page describes this for Docker Hub. A private registry behind the same proxy would need the same check; the page does not say so for private registries.

Do not use insecure-registries as the fix

The dockerd reference says the --insecure-registry option "creates security vulnerabilities" and "should only be enabled for testing purposes", and that "users should add their CA to their system's list of trusted CAs instead".

Confirm the fix

  1. docker pull registry.example.com:5000/app:1.0 completes.
  2. docker login registry.example.com:5000 reaches the credential prompt without the x509 error.
  3. The openssl s_client command with -verify_return_error connects, with -CAfile if the CA is only in certs.d.
  4. Every Docker host that pulls from this registry has been given the CA or the server sends a complete chain.

What to watch afterwards

  • The registry certificate's expiry date, and whether a renewal changes the issuing CA.
  • Any new Docker host: it needs the CA before its first pull.
  • Whether the registry sends its full chain after each renewal.

Risks and limits

  • These commands have not been run or lab-tested.
  • The Docker pages do not say whether the daemon must be restarted after a CA is added.
  • Red Hat family hosts use a different system trust tool and are not covered. Rootless Docker and Docker Desktop use different certificate directories.
  • A CA you trust can vouch for any name it signs. Trust only the CA that issued your registry's certificate.

Sources