grpc/grpc-go · error

grpctransport: Extensions is not set in ServerIdentifier

Error message

grpctransport: Extensions is not set in ServerIdentifier

What it means

Builder.Build requires that ServerIdentifier.Extensions is non-nil (grpc_transport.go:93-94), because the extension carries the ServerIdentifierExtension (including ConfigName) that selects which credentials configuration to use. A nil Extensions means there is no way to look up the transport config, so Build fails.

Source

Thrown at internal/xds/clients/grpctransport/grpc_transport.go:94

// the credentials from provided map of credentials names to
// credentials.Bundle.
func NewBuilder(configs map[string]Config) *Builder {
	return &Builder{
		configs:     configs,
		connections: make(map[clients.ServerIdentifier]*grpc.ClientConn),
		refs:        make(map[clients.ServerIdentifier]int),
	}
}

// Build returns a gRPC-based clients.Transport.
//
// The Extension field of the ServerIdentifier must be a ServerIdentifierExtension.
func (b *Builder) Build(si clients.ServerIdentifier) (clients.Transport, error) {
	if si.ServerURI == "" {
		return nil, fmt.Errorf("grpctransport: ServerURI is not set in ServerIdentifier")
	}
	if si.Extensions == nil {
		return nil, fmt.Errorf("grpctransport: Extensions is not set in ServerIdentifier")
	}
	sce, ok := si.Extensions.(ServerIdentifierExtension)
	if !ok {
		return nil, fmt.Errorf("grpctransport: Extensions field is %T, but must be %T in ServerIdentifier", si.Extensions, ServerIdentifierExtension{})
	}

	config, ok := b.configs[sce.ConfigName]
	if !ok {
		return nil, fmt.Errorf("grpctransport: unknown config name %q specified in ServerIdentifierExtension", sce.ConfigName)
	}
	if config.Credentials == nil {
		return nil, fmt.Errorf("grpctransport: config %q has nil credentials bundle", sce.ConfigName)
	}

	b.mu.Lock()
	defer b.mu.Unlock()

	if cc, ok := b.connections[si]; ok {

View on GitHub (pinned to 03255a9237)

Solutions

1. Set si.Extensions = grpctransport.ServerIdentifierExtension{ConfigName: "your-config"} before calling Build.
2. Ensure the ConfigName used matches a key passed to NewBuilder.
3. Add a precondition assertion that Extensions is non-nil in calling code.

Example fix

// before:
//   si := clients.ServerIdentifier{ServerURI: "dns:///xds:443"}
//   builder.Build(si) // Extensions nil
// after:
//   si := clients.ServerIdentifier{
//     ServerURI:  "dns:///xds:443",
//     Extensions: grpctransport.ServerIdentifierExtension{ConfigName: "default"},
//   }

func validateServerIdentifier(si clients.ServerIdentifier) error {
    if si.Extensions == nil {
        return errors.New("ServerIdentifier.Extensions must be set")
    }
    return nil
}

When it happens

Trigger: Calling builder.Build(si) where si.Extensions was never set. The Builder is documented to require an Extension of type ServerIdentifierExtension.

Common situations: Constructing a ServerIdentifier programmatically and forgetting the Extensions field; migrating from an older API that did not require Extensions.

Related errors

• grpctransport: ServerURI is not set in ServerIdentifier
• xds: required field `xds_servers` not found in bootstrap con
• jwt_token_file is required in JWT call credentials config
• grpctransport: unknown config name %q specified in ServerIde
• grpctransport: config %q has nil credentials bundle

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