Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

go build or go mod download inside Docker fails with an unknown authority error

Errortls: failed to verify certificate: x509: certificate signed by unknown authority

Short answer

Go inside the container found a certificate whose issuer is not in the trust store it reads. That is typical behind a company proxy that re-signs HTTPS traffic. Put the proxy's root certificate into the image and point Go at it with SSL_CERT_FILE. For image pulls, trust is the Docker daemon's, not Go's.

  • Applies to Go 1.24, Docker Engine 28, Docker Desktop on Windows
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out which program fails: the Go command inside the build step, or the Docker daemon pulling the base image. The line before the error tells you.

    docker build --progress=plain -t my-go-app . 2>&1 | grep -n -B3 "x509"
  2. 2Match what you see, then jump to its fix

    1. 1The error appears in a RUN go mod download or go build stepGo inside the build container does not trust the proxy's root certificateFix
    2. 2The error appears at the FROM line or while pulling the base image, before any Go step runsThe failing request is the Docker daemon's own pull, not Go'sFix

What does the error look like?

  • tls: failed to verify certificate: x509: certificate signed by unknown authority
  • the error appears in a RUN go mod download or go build step of a Dockerfile

Cause 1 of 2

Go inside the build container does not trust the proxy's root certificate

1Check

UnknownAuthorityError means the issuer of the certificate is unknown. Inside the build, the system store comes from the image, not from your Windows or Mac host.

docker run --rm golang:1.24 sh -c 'echo $SSL_CERT_FILE; ls /etc/ssl/certs | head -n 3'

2Fix

Copy your organisation's root certificate (PEM) into the image and set SSL_CERT_FILE or SSL_CERT_DIR so Go reads it. Go honours both variables as overrides for its default locations.

FROM golang:1.24
COPY corp-root-ca.pem /usr/local/share/corp-root-ca.pem
ENV SSL_CERT_FILE=/usr/local/share/corp-root-ca.pem
RUN go mod download

3Verify

Rebuild; the download step passes.

docker build --progress=plain -t my-go-app .

Confirmed by pkg.go.dev

Did this fix it?

Cause 2 of 2

The failing request is the Docker daemon's own pull, not Go's

1Check

The daemon trusts a registry's CA by a certificate placed in a directory named after that registry. On Linux these roots are merged with the host's system defaults; Docker Desktop can also use the host certificate store.

ls /etc/docker/certs.d/

2Fix

On a Linux engine, add the registry's CA file as a .crt in /etc/docker/certs.d/<registry-host>/ . On Docker Desktop, install the root certificate into the host's trusted store.

sudo mkdir -p /etc/docker/certs.d/registry.example.com
sudo cp ca.crt /etc/docker/certs.d/registry.example.com/ca.crt

3Verify

Pull the image again.

docker pull registry.example.com/team/base:latest

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Keep the corporate root certificate in the repository and copy it in a build stage, not in each project by hand.
  • Never disable verification to make a build pass; trust the right root instead.
  • Run the same Dockerfile on a machine outside the proxy in CI, to catch environment-only trust problems.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.