Fix TLSHandshakeError: tls: failed to verify certificate: x509: certificate signed by unknown authority in Go

This error occurs when Go's HTTP client cannot verify the server's TLS certificate because it is self-signed, issued by an unknown CA, or the system's CA bundle is missing. Fix it by adding the CA certificate to the system trust store or configuring a custom TLS config with the CA certificate. Never disable TLS verification in production.

Reading the Stack Trace

Here's what each line means:

• crypto/tls.(*Conn).verifyServerCertificate(0x14000196040, {0x14000226060, 0x1, 0x1}): Go's TLS client cannot verify the server's certificate against any trusted CA in the system certificate pool.
• main.callInternalAPI() /app/client/internal.go:18 +0x2d8: The callInternalAPI function at line 18 makes an HTTPS request to an internal service with a self-signed or private CA certificate.
• crypto/tls.(*clientHandshakeState).doFullHandshake(0x14000226000): The TLS handshake fails during certificate verification, before any HTTP data is exchanged.

Common Causes

func callInternalAPI() (*Response, error) {
	resp, err := http.Get("https://internal-service:8443/api/data")
	if err != nil {
		return nil, err // TLS verification failure
	}
	defer resp.Body.Close()
	// ...
}

FROM scratch
COPY app /app
CMD ["/app"]
# No CA certificates — all HTTPS requests fail

client := &http.Client{
	Transport: &http.Transport{
		TLSClientConfig: &tls.Config{
			InsecureSkipVerify: true, // INSECURE — never do this in production
		},
	},
}

The Fix

Load the internal CA certificate from a PEM file and add it to a custom certificate pool. Configure the HTTP client's TLS settings with this pool. This validates the internal certificate properly without disabling security.

func callInternalAPI() (*Response, error) {
	resp, err := http.Get("https://internal-service:8443/api/data")
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	var result Response
	json.NewDecoder(resp.Body).Decode(&result)
	return &result, nil
}

func newInternalClient(caCertPath string) (*http.Client, error) {
	caCert, err := os.ReadFile(caCertPath)
	if err != nil {
		return nil, fmt.Errorf("reading CA cert: %w", err)
	}

	caPool := x509.NewCertPool()
	if !caPool.AppendCertsFromPEM(caCert) {
		return nil, fmt.Errorf("failed to parse CA certificate")
	}

	return &http.Client{
		Timeout: 10 * time.Second,
		Transport: &http.Transport{
			TLSClientConfig: &tls.Config{
				RootCAs: caPool,
			},
		},
	}, nil
}

func callInternalAPI(client *http.Client) (*Response, error) {
	resp, err := client.Get("https://internal-service:8443/api/data")
	if err != nil {
		return nil, fmt.Errorf("calling internal API: %w", err)
	}
	defer resp.Body.Close()

	var result Response
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return nil, fmt.Errorf("decoding response: %w", err)
	}
	return &result, nil
}

Testing the Fix

package client_test

import (
	"crypto/tls"
	"crypto/x509"
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/stretchr/testify/assert"
)

func TestNewInternalClient_ValidCA(t *testing.T) {
	// Create a test server with TLS
	srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte(`{"status": "ok"}`))
	}))
	defer srv.Close()

	// Use the test server's CA cert
	caPool := x509.NewCertPool()
	for _, cert := range srv.TLS.Certificates {
		for _, c := range cert.Certificate {
			parsed, _ := x509.ParseCertificate(c)
			caPool.AddCert(parsed)
		}
	}

	client := &http.Client{
		Transport: &http.Transport{
			TLSClientConfig: &tls.Config{RootCAs: caPool},
		},
	}

	resp, err := client.Get(srv.URL)
	assert.NoError(t, err)
	assert.Equal(t, http.StatusOK, resp.StatusCode)
}

func TestNewInternalClient_InvalidCAPath(t *testing.T) {
	_, err := newInternalClient("/nonexistent/ca.pem")
	assert.Error(t, err)
	assert.Contains(t, err.Error(), "reading CA cert")
}

Run your tests:

go test ./client/... -v

Pushing Through CI/CD

git checkout -b fix/go-tls-handshake-error,git add client/internal.go client/internal_test.go,git commit -m "fix: configure custom CA cert pool for internal service TLS",git push origin fix/go-tls-handshake-error

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - run: go mod download
      - run: go vet ./...
      - run: go test ./... -race -coverprofile=coverage.out
      - run: go build ./...

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

go get github.com/bugstack/sdk

import "github.com/bugstack/sdk"

func init() {
  bugstack.Init(os.Getenv("BUGSTACK_API_KEY"))
}

Deploying the Fix (Manual Path)

1. Run go test ./... locally to confirm TLS connections work.
2. Open a pull request with the TLS configuration changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify internal service connections in staging.

Frequently Asked Questions