{"record":{"id":"f9f46496bac64d37","repo":"grpc/grpc-go","slug":"xds-required-field-xds-servers-not-found-in-boo","errorCode":null,"errorMessage":"xds: required field `xds_servers` not found in bootstrap configuration: %s","messagePattern":"xds: required field `xds_servers` not found in bootstrap configuration: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/xds/bootstrap/bootstrap.go","lineNumber":631,"sourceCode":"\t\tparser := getBuilder(nameAndConfig.PluginName)\n\t\tif parser == nil {\n\t\t\t// We ignore plugins that we do not know about.\n\t\t\tcontinue\n\t\t}\n\t\tbc, err := parser.ParseConfig(nameAndConfig.Config)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"xds: config parsing for certificate provider plugin %q failed during bootstrap: %v\", name, err)\n\t\t}\n\t\tcpcCfgs[instance] = bc\n\t}\n\tc.certProviderConfigs = cpcCfgs\n\n\t// Default value of the default client listener name template is \"%s\".\n\tif c.clientDefaultListenerResourceNameTemplate == \"\" {\n\t\tc.clientDefaultListenerResourceNameTemplate = \"%s\"\n\t}\n\tif len(c.xDSServers) == 0 {\n\t\treturn fmt.Errorf(\"xds: required field `xds_servers` not found in bootstrap configuration: %s\", string(data))\n\t}\n\n\t// Post-process the authorities' client listener resource template field:\n\t// - if set, it must start with \"xdstp://<authority_name>/\"\n\t// - if not set, it defaults to \"xdstp://<authority_name>/envoy.config.listener.v3.Listener/%s\"\n\tfor name, authority := range c.authorities {\n\t\tprefix := fmt.Sprintf(\"xdstp://%s\", url.PathEscape(name))\n\t\tif authority.ClientListenerResourceNameTemplate == \"\" {\n\t\t\tauthority.ClientListenerResourceNameTemplate = prefix + \"/envoy.config.listener.v3.Listener/%s\"\n\t\t\tcontinue\n\t\t}\n\t\tif !strings.HasPrefix(authority.ClientListenerResourceNameTemplate, prefix) {\n\t\t\treturn fmt.Errorf(\"xds: field clientListenerResourceNameTemplate %q of authority %q doesn't start with prefix %q\", authority.ClientListenerResourceNameTemplate, name, prefix)\n\t\t}\n\t}\n\treturn nil\n}\n","sourceCodeStart":613,"sourceCodeEnd":649,"githubUrl":"https://github.com/grpc/grpc-go/blob/03255a9237b6eb32710f6bc4f2de9a675b99fe36/internal/xds/bootstrap/bootstrap.go#L613-L649","documentation":"After the bootstrap JSON is successfully parsed the library checks that the xds_servers slice is non-empty (bootstrap.go:631). xds_servers is the only structurally required field because it tells the client where to connect for xDS resources. If the field is absent or set to an empty array, the bootstrap is considered invalid.","triggerScenarios":"The JSON is valid but the top-level xds_servers key is missing entirely, is misspelled (e.g. xds_server), or is present as an empty array. Also happens when a templating step strips the servers section for a non-production environment.","commonSituations":"Using a minimal/dev bootstrap that omits xds_servers by mistake; an overlay merged two configs and clobbered the servers; the envoy/bootstrap generator was configured without a management server URI.","solutions":["Add an xds_servers array with at least one server entry containing server_uri, channel_creds, and server_features.","Double-check the key spelling: it must be exactly xds_servers (snake_case, plural).","If using GRPC_XDS_BOOTSTRAP_CONFIG, ensure the inline JSON includes the full xds_servers block.","Regenerate the bootstrap with the intended management server endpoint."],"exampleFix":"// before:\n//   { \"node\": { \"id\": \"my-client\" } }\n// after:\n//   {\n//     \"xds_servers\": [{\n//       \"server_uri\": \"dns:///trafficdirector.googleapis.com:443\",\n//       \"channel_creds\": [{ \"type\": \"google_default\" }],\n//       \"server_features\": [\"xds_v3\"]\n//     }],\n//     \"node\": { \"id\": \"my-client\" }\n//   }","handlingStrategy":"validation","validationCode":"// Ensure xds_servers is present and non-empty before loading.\nfunc hasXDSServers(data []byte) error {\n    var probe struct{ XDSServers []json.RawMessage `json:\"xds_servers\"` }\n    if err := json.Unmarshal(data, &probe); err != nil {\n        return err\n    }\n    if len(probe.XDSServers) == 0 {\n        return errors.New(\"bootstrap missing required non-empty xds_servers\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat xds_servers as a required field in your bootstrap schema.","Diff new bootstrap configs against a known-good baseline before deploying.","Surface this error as a hard startup failure so it is never silently ignored."],"tags":["xds","bootstrap","config","required-field","grpc"],"analyzedSha":"03255a9237b6eb32710f6bc4f2de9a675b99fe36","analyzedAt":"2026-08-07T00:29:34.215Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}