grpc/grpc-java · critical · XdsInitializationException

Invalid bootstrap: missing 'server_uri'

Error message

Invalid bootstrap: missing 'server_uri'

What it means

Each entry in the 'xds_servers' bootstrap array must contain a 'server_uri' string identifying the control-plane server address. BootstrapperImpl.parseServerInfos throws XdsInitializationException when JsonUtil.getString(serverConfig, "server_uri") returns null, since a server entry without a URI is unusable.

Source

Thrown at xds/src/main/java/io/grpc/xds/client/BootstrapperImpl.java:264

    return builder;
  }

  protected Optional<Object> parseImplSpecificObject(
      @Nullable Map<String, ?> rawAllowedGrpcServices)
      throws XdsInitializationException {
    return Optional.empty();
  }

  private List<ServerInfo> parseServerInfos(List<?> rawServerConfigs, XdsLogger logger)
      throws XdsInitializationException {
    logger.log(XdsLogLevel.INFO, "Configured with {0} xDS servers", rawServerConfigs.size());
    ImmutableList.Builder<ServerInfo> servers = ImmutableList.builder();
    List<Map<String, ?>> serverConfigList = JsonUtil.checkObjectList(rawServerConfigs);
    for (Map<String, ?> serverConfig : serverConfigList) {
      String serverUri = JsonUtil.getString(serverConfig, "server_uri");
      if (serverUri == null) {
        throw new XdsInitializationException("Invalid bootstrap: missing 'server_uri'");
      }
      logger.log(XdsLogLevel.INFO, "xDS server URI: {0}", serverUri);

      Object implSpecificConfig = getImplSpecificConfig(serverConfig, serverUri);

      boolean resourceTimerIsTransientError = false;
      boolean ignoreResourceDeletion = false;
      boolean failOnDataErrors = false;
      // "For forward compatibility reasons, the client will ignore any entry in the list that it
      // does not understand, regardless of type."
      List<?> serverFeatures = JsonUtil.getList(serverConfig, "server_features");
      if (serverFeatures != null) {
        logger.log(XdsLogLevel.INFO, "Server features: {0}", serverFeatures);
        if (serverFeatures.contains(SERVER_FEATURE_IGNORE_RESOURCE_DELETION)) {
          ignoreResourceDeletion = true;
        }
        resourceTimerIsTransientError = xdsDataErrorHandlingEnabled
            && serverFeatures.contains(SERVER_FEATURE_RESOURCE_TIMER_IS_TRANSIENT_ERROR);

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Add "server_uri": "<address>" (e.g. "dns:///xds.example.com:443" or "unix:/path/to/socket") to every xds_servers entry.
2. Fix misspelled key names to exactly "server_uri".
3. Ensure the value is a non-null JSON string, not a placeholder or null literal.

Example fix

// before
"xds_servers": [{ "channel_creds": [{"type": "insecure"}] }]
// after
"xds_servers": [{ "server_uri": "dns:///xds.example.com:443",
                   "channel_creds": [{"type": "insecure"}] }]

for (Object o : xdsServers) {
  java.util.Map<String, ?> srv = (java.util.Map<String, ?>) o;
  Object uri = srv.get("server_uri");
  if (!(uri instanceof String) || ((String) uri).isEmpty()) {
    throw new IllegalStateException("xds_servers entry missing string 'server_uri'");
  }
}

boolean hasServerUri(java.util.Map<String, ?> serverConfig) {
  return serverConfig.get("server_uri") instanceof String
      && !((String) serverConfig.get("server_uri")).isEmpty();
}

When it happens

Trigger: An xds_servers entry missing the "server_uri" key, misspelling it (e.g. "uri", "serverUrl"), or giving a JSON null / non-string value.

Common situations: Hand-written bootstrap files; partially generated config where the templating dropped the address; copying config examples with placeholder addresses removed.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Invalid bootstrap: 'xds_servers' does not exist.
• client_listener_resource_name_template: '${clientListnerTemp
• Invalid bootstrap: '${fieldName}' does not exist.
• unsupported ExtAuthz service type: only grpc_service is supp
• Invalid ring hash function: " + ringHash.getHashFunction()

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/d3adfce4a2b57d7b. Report an issue: GitHub.