grpc/grpc-go · error

missing server_listener_resource_name_template in the bootst

Error message

missing server_listener_resource_name_template in the bootstrap configuration

What it means

Returned by xds.NewGRPCServer (xds/server.go:111) when the xDS bootstrap configuration does not provide a server_listener_resource_name_template. On the server side, this template is mandatory because it tells the xDS client how to request the Listener resource for the server's listener. Without it the xDS server cannot be configured, so construction fails.

Source

Thrown at xds/server.go:111

	// Initializing the xDS client upfront (instead of at serving time)
	// simplifies the code by eliminating the need for a mutex to protect the
	// xdsC and xdsClientClose fields.
	pool := xdsClientPool
	if s.opts.clientPoolForTesting != nil {
		pool = s.opts.clientPoolForTesting
	}
	xdsClient, xdsClientClose, err := pool.NewClient(xdsclient.NameForServer, mrl)
	if err != nil {
		return nil, fmt.Errorf("xDS client creation failed: %v", err)
	}

	// Validate the bootstrap configuration for server specific fields.

	// Listener resource name template is mandatory on the server side.
	cfg := xdsClient.BootstrapConfig()
	if cfg.ServerListenerResourceNameTemplate() == "" {
		xdsClientClose()
		return nil, errors.New("missing server_listener_resource_name_template in the bootstrap configuration")
	}

	s.xdsC = xdsClient
	s.xdsClientClose = xdsClientClose

	s.logger = internalgrpclog.NewPrefixLogger(logger, fmt.Sprintf(serverPrefix, s))
	s.logger.Infof("Created xds.GRPCServer")

	return s, nil
}

// handleServerOptions iterates through the list of server options passed in by
// the user, and handles the xDS server specific options.
func (s *GRPCServer) handleServerOptions(opts []grpc.ServerOption) {
	so := s.defaultServerOptions()
	for _, opt := range opts {
		if o, ok := opt.(*serverOption); ok {
			o.apply(so)

View on GitHub (pinned to 03255a9237)

Solutions

1. Add server_listener_resource_name_template (e.g. "grpc/server?xds.resource.listening_address=%s") to the x_servers section of your bootstrap JSON.
2. Ensure the GRPC_XDS_BOOTSTRAP / GRPC_XDS_BOOTSTRAP_FILE env var points to a bootstrap that includes server-side config.
3. Regenerate the bootstrap from your control plane with server mode enabled.
4. Verify the template is non-empty after bootstrap parsing (it must not be "").

Example fix

// before - bootstrap.json has only "xds_servers", no "x_servers"

// after - add the servers section
{
  "xds_servers": [...],
  "x_servers": [
    {
      "server_listener_resource_name_template": "grpc/server?xds.resource.listening_address=%s"
    }
  ]
}

cfg, _ := xdsclient.Get()
bc := cfg.BootstrapConfig()
if bc == nil || bc.ServerListenerResourceNameTemplate() == "" {
    log.Fatal("bootstrap missing server_listener_resource_name_template")
}

srv := xds.NewGRPCServer()
if _, err := srv.Serve(lis); err != nil {
    if strings.Contains(err.Error(), "server_listener_resource_name_template") {
        log.Fatalf("fix bootstrap config: %v", err)
    }
}

When it happens

Trigger: Creating an xds.GRPCServer while the bootstrap config (file or env GOOGLE_ANX_BOOSTRAP / GRPC_XDS_BOOTSTRAP) lacks the x_servers[].server_listener_resource_name_template field, or that field resolves to an empty string.

Common situations: Using a client-only bootstrap file for an xDS server; misgenerated bootstrap from a control plane; typo in the field name; bootstrap env var pointing at the wrong file.

Related errors

• xds: failed to JSON unmarshal server configurations during b
• xds: failed to JSON unmarshal server configuration during bo
• failed to build credentials bundle from bootstrap for %q: %v
• failed to build call credentials from bootstrap for %q: %v
• xds: `server_uri` field in server config cannot be empty: %s

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