xds: fetching trusted roots from CertificateProvider failed:

Error message

xds: fetching trusted roots from CertificateProvider failed: %v

What it means

Returned by the client-side TLS config builder when the root CertificateProvider's KeyMaterial call fails. On the client side a root provider is mandatory for verifying the server, so any failure to obtain trusted roots aborts the handshake setup. The wrapped error comes from the configured certprovider.Provider (e.g. filesystem, xDS).

Source

Thrown at internal/credentials/xds/handshake_info.go:224

	// On the client side, rootProvider is mandatory. IdentityProvider is
	// optional based on whether the client is doing TLS or mTLS.
	if hi.rootProvider == nil {
		return nil, errors.New("xds: CertificateProvider to fetch trusted roots is missing, cannot perform TLS handshake. Please check configuration on the management server")
	}

	// InsecureSkipVerify needs to be set to true because we need to perform
	// custom verification to check the SAN on the received certificate.
	// Currently the Go stdlib does complete verification of the cert (which
	// includes hostname verification) or none. We are forced to go with the
	// latter and perform the normal cert validation ourselves.
	cfg := &tls.Config{
		InsecureSkipVerify: true,
		NextProtos:         []string{"h2"},
	}

	km, err := hi.rootProvider.KeyMaterial(ctx)
	if err != nil {
		return nil, fmt.Errorf("xds: fetching trusted roots from CertificateProvider failed: %v", err)
	}
	cfg.RootCAs = km.Roots

	// If AutoHostSNI is true, and the endpoint hostname is present, we use the
	// endpoint hostname as the SNI value and also for SAN validation.
	// Otherwise, we use the SNI value from HandshakeInfo (which is configured
	// by the control plane) and validating SANs based on that.
	sni := hi.sni
	if hi.useAutoHostSNI && hostname != "" {
		sni = hostname
	}

	cfg.VerifyPeerCertificate = hi.buildVerifyFunc(km, true, sni)

	if hi.identityProvider != nil {
		km, err := hi.identityProvider.KeyMaterial(ctx)
		if err != nil {
			return nil, fmt.Errorf("xds: fetching identity certificates from CertificateProvider failed: %v", err)

View on GitHub (pinned to 03255a9237)

Solutions

Check the management server pushed the CertificateProvider resources (root cert) for this listener/cluster.
Verify file paths and permissions for any file-based certprovider mount.
Ensure the certprovider plugin is loaded and registered before the gRPC channel starts.
Wait for the provider to become ready (it surfaces KeyMaterial errors until the first update arrives) or restart after config propagation.

Defensive patterns

Strategy: retry

Try / catch

cfg, fallback, done, err := xds.ClientSideTLSConfig(ctx, hi, host)
if err != nil {
    if strings.Contains(err.Error(), "fetching trusted roots") {
        // back off; the certprovider likely has no material yet — retry after xDS update
    }
}

Prevention

Delay channel start until the certprovider reports it has key material.
Monitor certprovider KeyMaterial errors and alert before they affect handshakes.
Validate file-based provider paths at process startup.

When it happens

Trigger: Calling ClientSideTLSConfig -> clientSideTLSConfigInternal where hi.rootProvider.KeyMaterial(ctx) returns an error. Typical providers: certprovider.NewFileWatcherProvider with a missing/corrupt CA file, or an xDS-based provider whose certificate distribution has not completed.

Common situations: Misconfigured CertificateProvider plugin on the xDS management server; CA file path wrong or unreadable in the container; filesystem watcher hitting a rotated-away file; xDS resources not yet pushed so the provider has no material.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

AI-assisted analysis of grpc/grpc-go@03255a9237 (2026-08-07). Data as JSON: /api/errors/78555b530c6f9186. Report an issue: GitHub.