x509: Certificate Signed by Unknown Authority (Go, Docker, kubectl): How to Fix

The text is the Error() string of Go's x509.UnknownAuthorityError: «x509: certificate signed by unknown authority» (crypto/x509/verify.go). Go built the chain from what the server sent and could not reach any root in the certificate pool it was given. Since Go 1.20, crypto/tls wraps verification failures in CertificateVerificationError, so the full line usually reads tls: failed to verify certificate: x509: certificate signed by unknown authority (Go 1.20 release notes).

Sometimes a hint follows: (possibly because of "..." while trying to verify candidate authority certificate "..."). Go found a certificate that looked like the right issuer, but checking its signature failed, for example because of an unsupported algorithm or a mismatched key. That hint points at the chain contents rather than at a missing root.

Because Docker, Kubernetes tooling, Terraform, Helm and many CLIs are written in Go, the same text appears in docker pull, kubectl and others. Other languages report the same situation as unable to get local issuer certificate (OpenSSL) or PKIX path building failed (Java).

On Linux Go reads the first CA file it finds from a fixed list, including /etc/ssl/certs/ca-certificates.crt (Debian, Ubuntu), /etc/pki/tls/certs/ca-bundle.crt (Fedora, RHEL) and /etc/ssl/cert.pem (Alpine), plus certificate directories (crypto/x509/root_linux.go). A scratch image has none of them, so a statically linked Go binary that works on your laptop fails with this error in the container. The SSL_CERT_FILE and SSL_CERT_DIR environment variables override those locations (crypto/x509 SystemCertPool).

docker pull registry.example.com:5000/app fails with this error when the registry uses a private CA. The Docker daemon reads extra roots from a directory named after the registry: on a native Linux engine that is /etc/docker/certs.d/registry.example.com:5000/ca.crt, and every *.crt file there is added as a CA root (Docker documentation). Rootless Docker uses ~/.config/docker/certs.d instead, and Docker Desktop takes them from ~/.docker/certs.d on the host.

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

For kubectl, the trusted CA is the certificate-authority-data field of the cluster entry in your kubeconfig. If the cluster was rebuilt or its CA rotated, fetch a fresh kubeconfig from the cluster's provisioning tool instead of adding insecure-skip-tls-verify.

1. See who signed the server certificate:

   openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -E '^ *[0-9] s:|^ *i:'

   A public CA means the client lacks roots or the server lacks an intermediate; a company or product name means a private CA or a proxy.
2. Containers: add the bundle to the image. Multi-stage build into scratch:

   FROM golang:1.23 AS build
   # ... go build ...
   FROM scratch
   COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
   COPY --from=build /app /app

   On Alpine or Debian bases, install the ca-certificates package.
3. Private CA, system-wide: add the root to the OS store (update-ca-certificates or update-ca-trust), or point the process at a bundle with SSL_CERT_FILE=/etc/ssl/private/bundle.pem.
4. Private CA, in code: start from the system pool and append, so public sites keep working:

   pool, _ := x509.SystemCertPool()
   pool.AppendCertsFromPEM(rootPEM)
   client := &http.Client{Transport: &http.Transport{
       TLSClientConfig: &tls.Config{RootCAs: pool},
   }}

5. Do not set InsecureSkipVerify: true. It disables chain and host name checks for every connection that config makes.

docker run --rm your-image   # the request that failed should now succeed
openssl s_client -connect api.example.com:443 -servername api.example.com -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null 2>/dev/null | grep 'Verify return code'
# Verify return code: 0 (ok)

For a public endpoint, the SSL/TLS checker shows whether the chain your server sends reaches a publicly trusted root, which tells you whether to fix the server or the client.

• unable to get local issuer certificate — the OpenSSL and curl wording
• self-signed certificate in certificate chain — untrusted root sent by the server
• unable to verify the first certificate — missing intermediate in Node.js
• PKIX path building failed — Java's version
• NET::ERR_CERT_AUTHORITY_INVALID — the browser's version
• certificate has expired — a certificate in the chain is past notAfter