{"record":{"id":"f3bdb4c7bb35a98a","repo":"grpc/grpc-go","slug":"overriding-server-name-is-not-supported-by-xds-cli","errorCode":null,"errorMessage":"overriding server name is not supported by xDS client TLS credentials","messagePattern":"overriding server name is not supported by xDS client TLS credentials","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/xds/bootstrap/tlscreds/bundle.go","lineNumber":153,"sourceCode":"\t} else {\n\t\tconfig = &tls.Config{\n\t\t\tRootCAs:      km.Roots,\n\t\t\tCertificates: km.Certs,\n\t\t}\n\t}\n\treturn credentials.NewTLS(config).ClientHandshake(ctx, authority, rawConn)\n}\n\nfunc (c *reloadingCreds) Info() credentials.ProtocolInfo {\n\treturn credentials.ProtocolInfo{SecurityProtocol: \"tls\"}\n}\n\nfunc (c *reloadingCreds) Clone() credentials.TransportCredentials {\n\treturn &reloadingCreds{provider: c.provider}\n}\n\nfunc (c *reloadingCreds) OverrideServerName(string) error {\n\treturn errors.New(\"overriding server name is not supported by xDS client TLS credentials\")\n}\n\nfunc (c *reloadingCreds) ServerHandshake(net.Conn) (net.Conn, credentials.AuthInfo, error) {\n\treturn nil, nil, errors.New(\"server handshake is not supported by xDS client TLS credentials\")\n}\n\nfunc buildSPIFFEVerifyFunc(spiffeBundleMap map[string]*spiffebundle.Bundle) func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error {\n\treturn func(rawCerts [][]byte, _ [][]*x509.Certificate) error {\n\t\trawCertList := make([]*x509.Certificate, len(rawCerts))\n\t\tfor i, asn1Data := range rawCerts {\n\t\t\tcert, err := x509.ParseCertificate(asn1Data)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"spiffe: verify function could not parse input certificate: %v\", err)\n\t\t\t}\n\t\t\trawCertList[i] = cert\n\t\t}\n\t\tif len(rawCertList) == 0 {\n\t\t\treturn fmt.Errorf(\"spiffe: verify function has no valid input certificates\")","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/grpc/grpc-go/blob/0c51461d27177d997e14c642fe18c11668fc09a3/internal/xds/bootstrap/tlscreds/bundle.go#L135-L171","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Stop calling OverrideServerName on credentials obtained from tlscreds.NewBundle — the authority is fixed by the bootstrap configuration.","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.","Use `WithCredentialsBundle` with a fresh `credentials.NewTLS(...)` if you genuinely need runtime server-name override."],"exampleFix":"// before\ncreds := bundle.TransportCredentials()\ncreds.OverrideServerName(\"alt.example.com\") // -> error\n\n// after: do not override; rely on bootstrap / SNI from UpstreamTlsContext\n// or build a plain TLS bundle for the alternate target:\naltCreds := credentials.NewTLS(&tls.Config{ServerName: \"alt.example.com\"})","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"// Avoid calling OverrideServerName on credentials you do not own.\nfunc allowServerNameOverride(c credentials.TransportCredentials) bool {\n    // xDS bootstrap creds (tlscreds) reject overrides; everything else: check by type name if you must.\n    return !strings.Contains(fmt.Sprintf(\"%T\", c), \"reloadingCreds\")\n}","tryCatchPattern":"// If you cannot statically guarantee the cred type, attempt and recover gracefully.\nif err := creds.OverrideServerName(name); err != nil {\n    if strings.Contains(err.Error(), \"not supported by xDS client TLS credentials\") {\n        // Use a separate plain TLS bundle for this target instead.\n        creds = credentials.NewTLS(&tls.Config{ServerName: name})\n    } else {\n        return err\n    }\n}","preventionTips":["Treat xDS bootstrap TLS credentials as immutable with respect to authority.","Document at the seam where you hand out bootstrap creds that OverrideServerName is unsupported.","When a per-target authority is required, build a dedicated credentials.NewTLS for that target."],"tags":["grpc","xds","tls","mtls","credentials","bootstrap"],"backgroundTag":null,"analyzedSha":"0c51461d27177d997e14c642fe18c11668fc09a3","analyzedAt":"2026-08-11T14:49:15.055Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}