serverName for peer validation must be configured as a list…

Error message

serverName for peer validation must be configured as a list of acceptable SANs

What it means

Always returned by credsImpl.OverrideServerName. xDS credentials derive peer validation from the security configuration pushed by the management server (a list of acceptable SANs), so overriding the server name via the deprecated OverrideServerName method is intentionally unsupported. The error message tells the developer to configure SAN matching through xDS instead.

Solutions

Remove the OverrideServerName call for xDS credentials; configure SAN matching via the xDS security policy from the management server.
Use grpc.WithAuthority on the dial options to override the :authority header if that is the intent.
For the fallback credentials (non-xDS path), you may still call OverrideServerName on the fallback instance directly.

Example fix

// before
creds, _ := xds.NewClientCredentials(opts)
creds.OverrideServerName("example.com") // always errors
// after
creds, _ := xds.NewClientCredentials(opts)
conn, _ := grpc.Dial(addr, grpc.WithTransportCredentials(creds), grpc.WithAuthority("example.com"))

Defensive patterns

Strategy: validation

Validate before calling

// Do not call OverrideServerName on xDS credentials.
// Use grpc.WithAuthority for header override:
conn, err := grpc.Dial(addr, grpc.WithTransportCredentials(xdsCreds), grpc.WithAuthority("example.com"))

Prevention

Never call OverrideServerName on xDS credentials; it always errors.
Use grpc.WithAuthority for :authority header override.
Configure SAN matching via the xDS security policy from the management server.

When it happens

Trigger: Calling OverrideServerName on an xDS credentials instance. This method exists on the TransportCredentials interface but xDS implementations reject it unconditionally.

Common situations: Developers migrating from TLS credentials (where OverrideServerName or grpc.WithAuthority was used) to xDS credentials and attempting to reuse the same server-name override pattern. Legacy code that calls OverrideServerName generically on any TransportCredentials.

Related errors

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

Appendix: source

Thrown at credentials/xds/xds.go:229

		},
	}
	info.SPIFFEID = credinternal.SPIFFEIDFromState(conn.ConnectionState())
	return credinternal.WrapSyscallConn(rawConn, conn), info, nil
}

// Info provides the ProtocolInfo of this TransportCredentials.
func (c *credsImpl) Info() credentials.ProtocolInfo {
	return credentials.ProtocolInfo{SecurityProtocol: "tls"}
}

// Clone makes a copy of this TransportCredentials.
func (c *credsImpl) Clone() credentials.TransportCredentials {
	clone := *c
	return &clone
}

func (c *credsImpl) OverrideServerName(_ string) error {
	return errors.New("serverName for peer validation must be configured as a list of acceptable SANs")
}

// UsesXDS returns true if c uses xDS to fetch security configuration
// used at handshake time, and false otherwise.
func (c *credsImpl) UsesXDS() bool {
	return true
}

View on GitHub (pinned to 0c51461d27)