grpc/grpc-go · error

overriding server name is not supported by xDS client TLS cr

Error message

overriding server name is not supported by xDS client TLS credentials

What it means

The `reloadingCreds` transport credentials inside internal/xds/bootstrap/tlscreds/bundle.go implement gRFC A65 (mTLS credentials supplied via the xDS bootstrap file). These credentials hot-reload certs from a file_watcher provider and intentionally do not honor an authority/server-name override. Calling OverrideServerName returns this hard error at bundle.go:153 because the server name is bound to the bootstrap configuration and cannot be changed post-construction.

Source

Thrown at internal/xds/bootstrap/tlscreds/bundle.go:153

	} else {
		config = &tls.Config{
			RootCAs:      km.Roots,
			Certificates: km.Certs,
		}
	}
	return credentials.NewTLS(config).ClientHandshake(ctx, authority, rawConn)
}

func (c *reloadingCreds) Info() credentials.ProtocolInfo {
	return credentials.ProtocolInfo{SecurityProtocol: "tls"}
}

func (c *reloadingCreds) Clone() credentials.TransportCredentials {
	return &reloadingCreds{provider: c.provider}
}

func (c *reloadingCreds) OverrideServerName(string) error {
	return errors.New("overriding server name is not supported by xDS client TLS credentials")
}

func (c *reloadingCreds) ServerHandshake(net.Conn) (net.Conn, credentials.AuthInfo, error) {
	return nil, nil, errors.New("server handshake is not supported by xDS client TLS credentials")
}

func buildSPIFFEVerifyFunc(spiffeBundleMap map[string]*spiffebundle.Bundle) func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error {
	return func(rawCerts [][]byte, _ [][]*x509.Certificate) error {
		rawCertList := make([]*x509.Certificate, len(rawCerts))
		for i, asn1Data := range rawCerts {
			cert, err := x509.ParseCertificate(asn1Data)
			if err != nil {
				return fmt.Errorf("spiffe: verify function could not parse input certificate: %v", err)
			}
			rawCertList[i] = cert
		}
		if len(rawCertList) == 0 {
			return fmt.Errorf("spiffe: verify function has no valid input certificates")

View on GitHub (pinned to 0c51461d27)

Solutions

1. Stop calling OverrideServerName on credentials obtained from tlscreds.NewBundle — the authority is fixed by the bootstrap configuration.
2. If a different authority/SNI is required, configure it in the xDS bootstrap file or use a separate non-xDS TLS credentials bundle for that target.
3. Use `WithCredentialsBundle` with a fresh `credentials.NewTLS(...)` if you genuinely need runtime server-name override.

Example fix

// before
creds := bundle.TransportCredentials()
creds.OverrideServerName("alt.example.com") // -> error

// after: do not override; rely on bootstrap / SNI from UpstreamTlsContext
// or build a plain TLS bundle for the alternate target:
altCreds := credentials.NewTLS(&tls.Config{ServerName: "alt.example.com"})

// Avoid calling OverrideServerName on credentials you do not own.
func allowServerNameOverride(c credentials.TransportCredentials) bool {
    // xDS bootstrap creds (tlscreds) reject overrides; everything else: check by type name if you must.
    return !strings.Contains(fmt.Sprintf("%T", c), "reloadingCreds")
}

// If you cannot statically guarantee the cred type, attempt and recover gracefully.
if err := creds.OverrideServerName(name); err != nil {
    if strings.Contains(err.Error(), "not supported by xDS client TLS credentials") {
        // Use a separate plain TLS bundle for this target instead.
        creds = credentials.NewTLS(&tls.Config{ServerName: name})
    } else {
        return err
    }
}

When it happens

Trigger: Triggered when application code or another gRPC component calls `credentials.OverrideServerName(authority)` (or `grpc.WithAuthority` / `WithServerNameOverride`) on the TransportCredentials returned by `tlscreds.NewBundle`. This happens at bundle.go:152-154. The credentials produced by NewBundle are client-side mTLS credentials whose server-name identity is fixed by the bootstrap.

Common situations: Calling code mistakenly treats xDS bootstrap TLS credentials like ordinary `credentials.NewTLS` and tries to override the SNI/authority for a second target; combining `xds.NewCredentials` with helper code that sets `OverrideServerName`; upgrading to a version that wires bootstrap mTLS where previously a plain TLS cred was used and overridden.

Understand the failure class

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

Related errors

• failed to build credentials bundle from bootstrap for %q: %v
• xds: connection closed or HandshakeInfo dead
• xds: CertificateProvider to fetch trusted roots is missing,
• xds: CertificateProvider to fetch identity certificate is mi
• server handshake is not supported by xDS client TLS credenti

AI-assisted analysis of grpc/grpc-go@0c51461d27 (2026-08-11). Data as JSON: /api/errors/f3bdb4c7bb35a98a. Report an issue: GitHub.