{"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/0c51461d27177d997e14c642fe18c11668fc09a3/internal/xds/bootstrap/bootstrap.go#L613-L649","documentation":"Returned by Config.UnmarshalJSON when the xds_servers field is absent or an empty array. xds_servers is the only strictly required top-level field; without at least one management server the xDS client cannot operate.","triggerScenarios":"Triggered at bootstrap.go:631 when len(c.xDSServers) == 0 after unmarshalling succeeds structurally.","commonSituations":"Bootstrap file omits xds_servers; field misspelled (e.g. 'xdsServers'); GRPC_XDS_BOOTSTRAP env var points to a stale or wrong file that lacks the field.","solutions":["Add an xds_servers array with at least one valid server object.","Verify the GRPC_XDS_BOOTSTRAP / GRPC_XDS_BOOTSTRAP_FILE_NAME env var points to the intended file.","Check the field name spelling (snake_case xds_servers).","Regenerate the bootstrap from your control plane."],"exampleFix":"// before\n{\"node\":{\"id\":\"test\"}}\n\n// after\n{\"xds_servers\":[{\"server_uri\":\"trafficdirector.googleapis.com:443\",\"channel_creds\":[{\"type\":\"google_default\"}]}],\"node\":{\"id\":\"test\"}}","handlingStrategy":"validation","validationCode":"// Ensure xds_servers is present and non-empty before deploy.\nfunc hasXDSServers(data []byte) error {\n    var top struct {\n        XDSServers []json.RawMessage `json:\"xds_servers\"`\n    }\n    if err := json.Unmarshal(data, &top); err != nil {\n        return err\n    }\n    if len(top.XDSServers) == 0 {\n        return fmt.Errorf(\"xds_servers missing or empty\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if _, err := bootstrap.GetConfiguration(); err != nil {\n    if strings.Contains(err.Error(), \"xds_servers\") {\n        // add at least one server to the bootstrap.\n    }\n}","preventionTips":["Treat xds_servers as mandatory in your bootstrap template.","Point GRPC_XDS_BOOTSTRAP at a file you have validated.","Add a CI check that fails when xds_servers is absent."],"tags":["grpc","xds","bootstrap","config","required-field","go"],"backgroundTag":null,"analyzedSha":"0c51461d27177d997e14c642fe18c11668fc09a3","analyzedAt":"2026-08-11T14:49:15.055Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}