Why Your Self-Hosted Registry Fails with `x509: certificate signed by unknown authority`

If you run a self-hosted container registry, such as Harbor behind Nginx, you may encounter this frustrating error:

x509: certificate signed by unknown authority

I wrote a practical guide explaining what actually causes this error and how to fix it securely:

https://oscarchou.com/posts/troubleshoot/docker-x509-certificate-error-in-self-hosted-registry/

The most important detail is easy to overlook: although the user runs docker pull, the Docker CLI does not connect to the registry directly. It delegates the request to the Docker daemon, which acts as the TLS client and verifies the certificate presented by Nginx.

If the daemon cannot find the internal CA in its trusted certificates, it aborts the TLS handshake before the request reaches Harbor.

The guide uses diagrams to explain:

• How the Harbor, Nginx, and Docker components communicate

• Why the Docker daemon performs certificate verification

• Where Docker looks for trusted CAs

• How to install the CA under /etc/docker/certs.d

• Why insecure-registries is not a secure solution

If you are troubleshooting TLS for a self-hosted registry, I hope this guide saves you some time.