跳到主要内容

Go: x509: certificate signed by unknown authority — Causes, Fixes, and Debugging

Why Go Says “x509: certificate signed by unknown authority”

When a Go program makes an outbound TLS connection — http.Get, gRPC, a database driver, an AWS/GCP SDK call, a webhook — crypto/tls hands the peer’s certificate chain to crypto/x509 for verification. Verification walks from the leaf certificate up through any intermediates to a root certificate the process already trusts. If that walk dead-ends, you get:

x509: certificate signed by unknown authority

There are only three reasons the walk dead-ends:

  1. The root that signed the chain is not in the trust store Go is reading (private or internal CA).
  2. Go cannot read any trust store at all (container image without ca-certificates).
  3. The server did not send the intermediate certificates, so the walk cannot reach a root that is trusted.

Two facts explain most of the confusion around this error:

  • Go never uses the browser trust store. On Linux it reads PEM bundle files from a fixed list of paths: /etc/ssl/certs/ca-certificates.crt, /etc/pki/tls/certs/ca-bundle.crt, /etc/ssl/cert.pem, /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem, and a few more. On macOS and Windows (Go 1.18+) it delegates to the OS verifier instead.
  • Go never fetches missing intermediates over the network. Browsers and Windows chase the AIA extension in the leaf certificate; Go does not. The server must send the full chain.

Reproduce It in Under a Minute

A minimal reproduction that isolates the problem from your application logic:

package main

import (
	"fmt"
	"net/http"
)

func main() {
	resp, err := http.Get("https://internal.example.com/healthz")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
	fmt.Println(resp.Status)
}

On Go 1.20 and later the error is wrapped by crypto/tls, so the full string is longer than the classic one:

$ go run .
Get "https://internal.example.com/healthz": tls: failed to verify certificate: x509: certificate signed by unknown authority

On Go 1.19 and earlier you get the bare x509: message with no tls: failed to verify certificate prefix. Both mean the same thing.

Three commands tell you which of the three root causes you are hitting:

# 1. Does a trust store even exist in this environment?
ls -l /etc/ssl/certs/ca-certificates.crt /etc/pki/tls/certs/ca-bundle.crt 2>/dev/null

# 2. How many certificates is the server actually sending?
openssl s_client -connect internal.example.com:443 -servername internal.example.com 
  -showcerts </dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE"

# 3. What is the subject/issuer of each certificate in the chain?
openssl s_client -connect internal.example.com:443 -servername internal.example.com 
  -showcerts </dev/null 2>/dev/null | grep -E "^(s|i):"

A count of 1 in step 2 is an immediate red flag: the server is sending the leaf only.

Cause 1: The Container Image Has No CA Bundle

This is the single most common cause. A scratch, alpine, or hand-rolled base image has no trust store until you install one. The binary runs fine on your laptop and fails the moment it talks to any HTTPS endpoint in the container.

Alpine (the classic case — the ca-certificates package is not installed by default):

FROM alpine:3.20
RUN apk add --no-cache ca-certificates && update-ca-certificates
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]

Debian / Ubuntu:

RUN apt-get update 
 && apt-get install -y --no-install-recommends ca-certificates 
 && rm -rf /var/lib/apt/lists/*

RHEL / UBI / Fedora:

RUN microdnf install -y ca-certificates && update-ca-trust && microdnf clean all

scratch — copy the bundle from a stage that has it:

FROM golang:1.23-alpine AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/app ./cmd/app

FROM scratch
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]

Distroless already ships the bundle, so prefer it over scratch unless you have a hard size constraint:

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]

Verify the file is actually present in the final image (there is no shell in scratch, so export and inspect):

docker create --name tmp your-image
docker export tmp | tar -tv | grep ca-certificates
docker rm tmp

If nothing is printed, the image has no CA bundle and every public HTTPS call from it will fail.

Cause 2: A Private or Internal CA That Go Does Not Trust

If the endpoint is signed by an internal PKI, no amount of installing ca-certificates will help — that package only contains the public Mozilla root set. You must make Go trust your root, either process-wide via environment variables or per-client in code.

Option A: environment variables (whole process)

# IMPORTANT: SSL_CERT_FILE REPLACES the default bundle. It does not extend it.
# Concatenate the system bundle with your root first.
cat /etc/ssl/certs/ca-certificates.crt /etc/pki/internal/root-ca.pem > /etc/ssl/certs/combined.pem
export SSL_CERT_FILE=/etc/ssl/certs/combined.pem

# Alternative: a directory of hashed certificates (run c_rehash on it)
export SSL_CERT_DIR=/etc/ssl/internal/certs

In Kubernetes, mount the bundle from a ConfigMap and set the variable on the container:

spec:
  containers:
    - name: app
      env:
        - name: SSL_CERT_FILE
          value: /etc/ssl/internal/combined.pem
      volumeMounts:
        - name: internal-ca
          mountPath: /etc/ssl/internal
          readOnly: true
  volumes:
    - name: internal-ca
      configMap:
        name: internal-ca-bundle

Option B: a dedicated root pool in code (one client only)

package main

import (
	"crypto/tls"
	"crypto/x509"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	pem, err := os.ReadFile("/etc/ssl/internal/root-ca.pem")
	if err != nil {
		panic(err)
	}

	pool := x509.NewCertPool()
	if !pool.AppendCertsFromPEM(pem) {
		panic("no certificates parsed from PEM")
	}

	client := &http.Client{
		Transport: &http.Transport{
			TLSClientConfig: &tls.Config{
				RootCAs:    pool,
				MinVersion: tls.VersionTLS12,
			},
		},
	}

	resp, err := client.Get("https://internal.example.com/healthz")
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(body))
}

If you need both public and internal endpoints from the same client, start from the system pool and append:

pool, err := x509.SystemCertPool()
if err != nil {
	return err
}
pool.AppendCertsFromPEM(pem) // adds to the copy, leaves the system store untouched

Windows caveat: x509.SystemCertPool() returns an empty pool on Windows. Appending your private root and setting RootCAs therefore disables the OS verifier, and public sites start failing. On Windows, install the root into the machine certificate store (certutil -addstore Root root-ca.pem) or use two separate clients.

Cause 3: The Server Sends an Incomplete Chain

Everything on your side can be correct and this still fails. If the server sends only the leaf certificate, the client has no way to connect the leaf’s issuer to a trusted root — and Go will not go fetch the intermediate.

Detect it by counting certificates in the handshake:

openssl s_client -connect internal.example.com:443 -servername internal.example.com 
  -showcerts </dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE"

One certificate means the chain is incomplete. A correct chain is leaf + intermediate(s), usually 2 or 3 certificates.

To confirm the intermediate is the missing piece, verify the chain against the root using the intermediates you have:

# Save the chain the server sends
openssl s_client -connect internal.example.com:443 -servername internal.example.com 
  -showcerts </dev/null 2>/dev/null 
  | sed -n '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p' > chain.pem

# Split into cert1.pem (leaf), cert2.pem, cert3.pem ...
awk 'BEGIN{n=0} /BEGIN CERT/{n++} {print > "cert"n".pem"}' chain.pem

# Verify the leaf against the root, supplying intermediates as untrusted
openssl verify -CAfile /path/to/root-ca.pem -untrusted chain.pem cert1.pem

If that succeeds but your Go program fails, the chain is fine and the problem is the client’s trust store. If it fails with error 21 at 0 depth lookup: unable to verify the first certificate, the intermediate is genuinely missing.

Fix it on the server side. In nginx, the bundle must be leaf first, then intermediates:

# fullchain.pem = server cert + intermediate(s), concatenated in that order
ssl_certificate     /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;

Do not include the root in the served chain — it adds bytes to every handshake and gains nothing.

Fix Comparison Table

Scenario Typical symptom Fix Where to apply
scratch / distroless image with no bundle Every public HTTPS call fails, nothing works Copy ca-certificates.crt into the image, or switch to distroless/static Dockerfile
Alpine base image Works on Debian base, fails after switching to Alpine apk add --no-cache ca-certificates && update-ca-certificates Dockerfile
Private CA, whole process Only internal hosts fail; public hosts fine SSL_CERT_FILE pointing at a combined bundle Deployment env / systemd unit
Private CA, single client One service client fails, rest of the app fine tls.Config{RootCAs: pool} Go code
Server sends leaf only curl/browsers work, Go fails Serve the full chain (leaf + intermediates) nginx / Envoy / ALB
Corporate TLS-inspecting proxy All external hosts fail in CI only Append the proxy root to the bundle used by CI CI environment
macOS / Windows developer machine Works in prod, fails locally Install the root into the OS keychain / cert store Operating system
Local test only You just want the test to pass InsecureSkipVerify: true — never in production Go code, test build tag

Troubleshooting: Real Error Strings Decoded

1. x509: certificate signed by unknown authority

The bare form, seen on Go 1.19 and earlier or when the error is formatted with %v deep in a library. Run the three triage commands from the first section: check the bundle exists, check the chain length, check whether the root is private.

2. tls: failed to verify certificate: x509: certificate signed by unknown authority

Go 1.20+ wraps the x509 error in a *tls.CertificateVerificationError. The wrapper is the reason string matching broke when you upgraded. Unwrap it properly:

var verifyErr *tls.CertificateVerificationError
if errors.As(err, &verifyErr) {
	log.Printf("cert verify failed: %v", verifyErr.Err)
}

3. x509: certificate signed by unknown authority (possibly because of "crypto/rsa: verification error" while trying to verify candidate authority certificate "Corp Root CA")

This one is different and easy to misread. Go did find a root whose subject matches the issuer — but the signature check against that root’s public key failed. In practice it means you have a stale root with the same distinguished name as the current one (a re-issued CA that kept its CN), or you concatenated a root with a truncated/corrupt copy of itself.

# List every certificate in the bundle with subject + fingerprint to spot duplicates
openssl crl2pkcs7 -nocrl -certfile /etc/ssl/certs/combined.pem 
  | openssl pkcs7 -print_certs -noout

Remove the old root. Same message with x509: ECDSA verification failure means the same thing for an ECDSA-signed CA.

4. x509: certificate has expired or is not yet valid: current time 2025-03-01T12:00:00Z is after 2025-02-28T00:00:00Z

Not an authority problem, but frequently reported as one. Either the certificate really expired, or the container’s clock is wrong (common on resumed VMs and in some CI runners). Check with date -u inside the container and compare to the NotAfter from openssl x509 -noout -dates.

5. x509: certificate is valid for *.example.com, not internal.example.com

A hostname mismatch, not a trust failure. A wildcard covers exactly one label: *.example.com matches api.example.com but not api.internal.example.com. Reissue with the right SAN.

6. x509: cannot validate certificate for 10.0.0.5 because it doesn't contain any IP SANs

You dialed by IP. Certificates validate against IP SANs, not DNS SANs. Connect by hostname, or reissue with the IP in the SAN list.

7. x509: cannot verify signature: insecure algorithm SHA1-RSA

Go 1.18+ rejects SHA-1 signatures by default. An old intermediate or root in your chain is SHA-1 signed. Reissue the chain with SHA-256; there is no supported workaround worth using.

8. x509: certificate relies on legacy Common Name field, use SANs instead

The certificate has no Subject Alternative Name and only a CN. Go has ignored CN for hostname matching since 1.15. Reissue the certificate with a proper SAN extension.

Verify the Fix

Confirm the trust store Go will actually load, including the effect of SSL_CERT_FILE:

package main

import (
	"crypto/x509"
	"fmt"
	"os"
)

func main() {
	pool, err := x509.SystemCertPool()
	if err != nil {
		fmt.Fprintln(os.Stderr, "SystemCertPool:", err)
		os.Exit(1)
	}
	fmt.Printf("trusted roots: %dn", len(pool.Subjects())) // Subjects is deprecated but fine for debugging
}

Run it three ways to isolate the layer that is broken:

# Baseline: whatever the environment currently provides
go run ./cmd/trustcheck

# Explicitly point at your root
SSL_CERT_FILE=/etc/ssl/internal/root-ca.pem go run ./cmd/trustcheck

# Force Go's embedded fallback roots (Go 1.20+).
# If this succeeds where the baseline fails, the system bundle is missing or corrupt.
GODEBUG=x509usefallbackroots=1 go run ./cmd/trustcheck

Then verify the server side one more time from inside the actual runtime, not your laptop:

docker run --rm -e SSL_CERT_FILE=/etc/ssl/internal/combined.pem your-image

# Confirm the served chain has the intermediate
openssl s_client -connect internal.example.com:443 -servername internal.example.com 
  -showcerts </dev/null 2>/dev/null | grep -E "^(s|i):"

Finally, pin the behaviour in a test so the regression cannot come back:

func TestInternalEndpointTrusted(t *testing.T) {
	pool := x509.NewCertPool()
	pem, err := os.ReadFile("testdata/root-ca.pem")
	if err != nil {
		t.Fatal(err)
	}
	if !pool.AppendCertsFromPEM(pem) {
		t.Fatal("failed to parse root CA")
	}
	client := &http.Client{Transport: &http.Transport{
		TLSClientConfig: &tls.Config{RootCAs: pool},
	}}
	resp, err := client.Get(ts.URL)
	if err != nil {
		t.Fatal(err)
	}
	resp.Body.Close()
}

FAQ

Does Go use the operating system or browser trust store?

It depends on the platform. On Linux, Go reads PEM bundle files from a fixed list of paths and never talks to NSS or the browser store. On macOS and Windows with Go 1.18+, it calls the platform verifier, so the OS store is used. This is why the same code can pass on a developer Mac and fail in a Linux container.

Why does curl work but my Go program fails?

Three usual reasons. curl may be reading a different bundle (many distros ship curl with its own compiled-in CA path, and CURL_CA_BUNDLE may be set). curl may be following the AIA extension to fetch a missing intermediate, which Go never does. Or curl is running on your host while the Go binary runs inside a container that has no bundle at all.

Does SSL_CERT_FILE add to the default bundle or replace it?

It replaces it. Once SSL_CERT_FILE is set, Go loads only that file. This is the number one self-inflicted wound in this area: someone points SSL_CERT_FILE at their private root, internal calls start working, and every public HTTPS call in the process breaks. Always build a combined bundle: cat system-bundle.pem private-root.pem > combined.pem.

Do I need to add the root or the intermediate certificate?

The root. The client’s trust store holds roots; intermediates belong in the chain the server sends. If you control neither the server nor the root, adding the intermediate to your bundle also works, but it is fragile — intermediates rotate far more often than roots.

Can I just set InsecureSkipVerify to make it go away?

Only in tests, and only with a build tag so it cannot ship. InsecureSkipVerify: true disables hostname verification as well as chain validation, so the connection becomes trivially interceptable. If the certificate is self-signed and you control both ends, use RootCAs with the self-signed certificate — it is one extra line and keeps the connection authenticated.

Why does it work locally but fail inside Docker or Kubernetes?

Because the image is a different trust environment. Local development uses the host’s full CA store; the image uses whatever you installed, which for alpine, scratch, and many slim bases is nothing. Check with ls /etc/ssl/certs/ca-certificates.crt inside the running container before changing any application code.

How do I add a private CA on macOS or Windows?

Install it into the OS store, not into an environment variable. On macOS, add the certificate to the System keychain and mark it as trusted (security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain root-ca.pem). On Windows, certutil -addstore -f Root root-ca.pem from an elevated prompt. Note that SSL_CERT_FILE is ignored on these platforms when the platform verifier is active, which is the default since Go 1.18.

What is SSL_CERT_DIR for?

It points at a directory of individual certificate files named by their OpenSSL hash (c_rehash format), colon-separated for multiple directories. It is an alternative to SSL_CERT_FILE and follows the same replacement semantics. Most teams are better served by a single concatenated PEM file, since it is easier to mount as a Kubernetes ConfigMap and to diff in review.