{"record":{"id":"9fc218fa53e38bd4","repo":"grpc/grpc-go","slug":"servername-for-peer-validation-must-be-configured","errorCode":null,"errorMessage":"serverName for peer validation must be configured as a list of acceptable SANs","messagePattern":"serverName for peer validation must be configured as a list of acceptable SANs","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"credentials/xds/xds.go","lineNumber":229,"sourceCode":"\t\t},\n\t}\n\tinfo.SPIFFEID = credinternal.SPIFFEIDFromState(conn.ConnectionState())\n\treturn credinternal.WrapSyscallConn(rawConn, conn), info, nil\n}\n\n// Info provides the ProtocolInfo of this TransportCredentials.\nfunc (c *credsImpl) Info() credentials.ProtocolInfo {\n\treturn credentials.ProtocolInfo{SecurityProtocol: \"tls\"}\n}\n\n// Clone makes a copy of this TransportCredentials.\nfunc (c *credsImpl) Clone() credentials.TransportCredentials {\n\tclone := *c\n\treturn &clone\n}\n\nfunc (c *credsImpl) OverrideServerName(_ string) error {\n\treturn errors.New(\"serverName for peer validation must be configured as a list of acceptable SANs\")\n}\n\n// UsesXDS returns true if c uses xDS to fetch security configuration\n// used at handshake time, and false otherwise.\nfunc (c *credsImpl) UsesXDS() bool {\n\treturn true\n}\n","sourceCodeStart":211,"sourceCodeEnd":237,"githubUrl":"https://github.com/grpc/grpc-go/blob/03255a9237b6eb32710f6bc4f2de9a675b99fe36/credentials/xds/xds.go#L211-L237","documentation":"Returned unconditionally by credsImpl.OverrideServerName (credentials/xds/xds.go:229). With xDS credentials, peer identity is validated via SAN matchers pushed by the management server, not via a single OverrideServerName string, so the standard TransportCredentials.OverrideServerName API is intentionally disabled and always errors.","triggerScenarios":"Calling OverrideServerName on xDS credentials — directly, or via a helper (e.g. grpc.WithTransportCredentials + WithServerTransportCredentials wrappers, or credentials.CallInfoServerName / old sample code) that invokes OverrideServerName. It always returns this error for xDS creds.","commonSituations":"Porting code that used credentials.NewTLS and OverrideServerName to xDS credentials; using a utility that calls OverrideServerName on any TransportCredentials; older tutorials showing OverrideServerName usage.","solutions":["Do not call OverrideServerName on xDS credentials — remove the call entirely.","Configure peer validation through the xDS control plane (SAN matchers / validation context) instead of client-side override.","If you need a fixed server name, set SNI/hostname via the xDS Listener/Route config or the dial target authority, not OverrideServerName."],"exampleFix":"// before\nc, _ := xds.NewClientCredentials(xds.ClientOptions{FallbackCreds: insecure.NewCredentials()})\nc.OverrideServerName(\"example.com\") // always errors\n\n// after\nc, _ := xds.NewClientCredentials(xds.ClientOptions{FallbackCreds: insecure.NewCredentials()})\n// peer validation is configured via SAN matchers on the xDS management server","handlingStrategy":"validation","validationCode":"// Never call OverrideServerName on xDS credentials.\n// If you have a generic helper that calls it, skip xDS creds:\nfunc maybeOverride(c credentials.TransportCredentials, name string) error {\n    if c.UsesXDS != nil && c.UsesXDS() {\n        return nil // xDS: peer validation comes from SAN matchers\n    }\n    return c.OverrideServerName(name)\n}","typeGuard":null,"tryCatchPattern":"if err := c.OverrideServerName(name); err != nil {\n    // for xDS creds this always errors; treat as expected and move on,\n    // or avoid calling it in the first place\n}","preventionTips":["Do not call OverrideServerName on xDS credentials at all.","Configure peer validation (SAN matchers) on the xDS control plane."],"tags":["go","grpc","security","xds","credentials","misuse"],"analyzedSha":"03255a9237b6eb32710f6bc4f2de9a675b99fe36","analyzedAt":"2026-08-07T00:29:34.215Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}