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

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.

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 03255a9237)

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.

Example fix

// before
c, _ := xds.NewClientCredentials(xds.ClientOptions{FallbackCreds: insecure.NewCredentials()})
c.OverrideServerName("example.com") // always errors

// after
c, _ := xds.NewClientCredentials(xds.ClientOptions{FallbackCreds: insecure.NewCredentials()})
// peer validation is configured via SAN matchers on the xDS management server

Defensive patterns

Strategy: validation

Validate before calling

// Never call OverrideServerName on xDS credentials.
// If you have a generic helper that calls it, skip xDS creds:
func maybeOverride(c credentials.TransportCredentials, name string) error {
    if c.UsesXDS != nil && c.UsesXDS() {
        return nil // xDS: peer validation comes from SAN matchers
    }
    return c.OverrideServerName(name)
}

Try / catch

if err := c.OverrideServerName(name); err != nil {
    // for xDS creds this always errors; treat as expected and move on,
    // or avoid calling it in the first place
}

Prevention

Do not call OverrideServerName on xDS credentials at all.
Configure peer validation (SAN matchers) on the xDS control plane.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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