{"record":{"id":"2be4c0ded3f43290","repo":"grpc/grpc-java","slug":"invalid-bootstrap-xds-servers-does-not-exist","errorCode":null,"errorMessage":"Invalid bootstrap: 'xds_servers' does not exist.","messagePattern":"Invalid bootstrap: 'xds_servers' does not exist\\.","errorType":"exception","errorClass":"XdsInitializationException","httpStatus":null,"severity":"critical","filePath":"xds/src/main/java/io/grpc/xds/client/BootstrapperImpl.java","lineNumber":121,"sourceCode":"      throw new XdsInitializationException(\"Failed to parse JSON\", e);\n    }\n\n    logger.log(XdsLogLevel.DEBUG, \"Bootstrap configuration:\\n{0}\", rawBootstrap);\n    return bootstrap(rawBootstrap);\n  }\n\n  @Override\n  public BootstrapInfo bootstrap(Map<String, ?> rawData) throws XdsInitializationException {\n    return bootstrapBuilder(rawData).build();\n  }\n\n  protected BootstrapInfo.Builder bootstrapBuilder(Map<String, ?> rawData)\n      throws XdsInitializationException {\n    BootstrapInfo.Builder builder = BootstrapInfo.builder();\n\n    List<?> rawServerConfigs = JsonUtil.getList(rawData, \"xds_servers\");\n    if (rawServerConfigs == null) {\n      throw new XdsInitializationException(\"Invalid bootstrap: 'xds_servers' does not exist.\");\n    }\n    List<ServerInfo> servers = parseServerInfos(rawServerConfigs, logger);\n    if (servers.size() > 1 && !enableXdsFallback) {\n      servers = ImmutableList.of(servers.get(0));\n    }\n    builder.servers(servers);\n\n    Node.Builder nodeBuilder = Node.newBuilder();\n    Map<String, ?> rawNode = JsonUtil.getObject(rawData, \"node\");\n    if (rawNode != null) {\n      String id = JsonUtil.getString(rawNode, \"id\");\n      if (id != null) {\n        logger.log(XdsLogLevel.INFO, \"Node id: {0}\", id);\n        nodeBuilder.setId(id);\n      }\n      String cluster = JsonUtil.getString(rawNode, \"cluster\");\n      if (cluster != null) {\n        logger.log(XdsLogLevel.INFO, \"Node cluster: {0}\", cluster);","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/client/BootstrapperImpl.java#L103-L139","documentation":"During bootstrap parsing, BootstrapperImpl.bootstrapBuilder() requires a top-level 'xds_servers' array in the bootstrap configuration. If JsonUtil.getList(rawData, \"xds_servers\") returns null, the configuration is rejected with XdsInitializationException because the client has no control-plane servers to connect to.","triggerScenarios":"Bootstrap JSON lacking the 'xds_servers' key entirely, misspelling it (e.g. 'xdsServers', 'xds_server'), or providing a non-list value for it; empty JSON object {} as the bootstrap config.","commonSituations":"Following an outdated or wrong-version bootstrap spec (pre-xDS bootstrap v2/v3 examples); hand-writing minimal bootstrap files; tools that emit ADS config under a different key.","solutions":["Add a top-level \"xds_servers\" array to the bootstrap JSON with at least one server object containing \"server_uri\" and \"channel_creds\".","Fix the key spelling — it must be exactly \"xds_servers\".","Validate the file against the gRPC xDS bootstrap v3 JSON schema before deploying.","Regenerate the bootstrap file using your mesh's official bootstrap generation tool."],"exampleFix":"// before\n{ \"node\": { \"id\": \"backend\" } }\n// after\n{\n  \"xds_servers\": [{ \"server_uri\": \"dns:///xds.example.com:443\",\n                     \"channel_creds\": [{\"type\": \"insecure\"}] }]\n}","handlingStrategy":"validation","validationCode":"java.util.Map<String, ?> cfg = parseBootstrapJson();\nif (!(cfg.get(\"xds_servers\") instanceof java.util.List) ||\n    ((java.util.List<?>) cfg.get(\"xds_servers\")).isEmpty()) {\n  throw new IllegalStateException(\"bootstrap missing non-empty 'xds_servers' list\");\n}","typeGuard":"boolean hasXdsServers(java.util.Map<String, ?> cfg) {\n  return cfg.get(\"xds_servers\") instanceof java.util.List\n      && !((java.util.List<?>) cfg.get(\"xds_servers\")).isEmpty();\n}","tryCatchPattern":null,"preventionTips":["Validate bootstrap files against the gRPC xDS bootstrap v3 schema in CI.","Use exact key names from the spec: \"xds_servers\", \"server_uri\", \"channel_creds\".","Prefer generated bootstrap files from your mesh tooling over hand-written ones."],"tags":["grpc","xds","bootstrap","config-validation"],"backgroundTag":"missing-required-config-field","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}