xds: fetching identity certificates from CertificateProvider

Error message

xds: fetching identity certificates from CertificateProvider failed: %v

What it means

Returned by the client-side TLS config builder when mTLS is configured (identityProvider is set) and hi.identityProvider.KeyMaterial(ctx) fails. The client cannot present a client certificate, so the mTLS handshake setup is aborted. The wrapped error is from the identity certprovider.

Source

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

		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)
		}
		cfg.Certificates = km.Certs
	}

	if envconfig.XDSSNIEnabled && sni != "" {
		cfg.ServerName = sni
	}
	return cfg, nil
}

func (hi *HandshakeInfo) buildVerifyFunc(km *certprovider.KeyMaterial, isClient bool, sni string) func(rawCerts [][]byte, _ [][]*x509.Certificate) error {
	return func(rawCerts [][]byte, _ [][]*x509.Certificate) error {
		if len(rawCerts) == 0 {
			return fmt.Errorf("xds: no peer certificates presented")
		}
		// Parse all raw certificates presented by the peer.
		var certs []*x509.Certificate
		for _, rc := range rawCerts {

View on GitHub (pinned to 03255a9237)

Solutions

Confirm the identity CertificateProvider resource is configured on the management server for this cluster.
Verify the workload's SPIRE agent is running and has issued a client cert.
Check filesystem paths/permissions for file-based identity providers.
If mTLS is not actually required, drop the identityProvider from HandshakeInfo so the client does TLS instead of mTLS.

Defensive patterns

Strategy: retry

Try / catch

if _, _, _, err := xds.ClientSideTLSConfig(ctx, hi, host); err != nil {
    if strings.Contains(err.Error(), "fetching identity certificates") {
        // identity provider not ready; retry once xDS delivers the client cert
    }
}

Prevention

Ensure the client workload has an issued SVID before establishing mTLS channels.
Keep the SPIRE agent healthy so identity material is always available.
Drop the identityProvider if one-way TLS is acceptable.

When it happens

Trigger: clientSideTLSConfigInternal at handshake_info.go:240, when the identity provider (the one supplying client certs) cannot produce key material — e.g. its cert file is missing or the xDS side has not delivered the identity cert.

Common situations: mTLS enabled on the cluster but the identity provider resource is missing from the xDS config; SPIRE/agent not running so no client cert is available; file path misconfigured; cert rotation gap where the old cert was removed before the new arrived.

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/6405d99c2fd4d6cd. Report an issue: GitHub.