grpc/grpc-java · critical · XdsInitializationException

Invalid bootstrap: '${fieldName}' does not exist.

Error message

Invalid bootstrap: '${fieldName}' does not exist.

What it means

BootstrapperImpl.checkForNull is a generic validator used while parsing server config fields (e.g. channel creds type, cert paths) during bootstrap. Any required field whose extracted value is null produces XdsInitializationException("Invalid bootstrap: '<fieldName>' does not exist.").

Source

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

  /**
   * Reads the content of the file with the given path in the file system.
   */
  public interface FileReader {
    String readFile(String path) throws IOException;
  }

  protected enum LocalFileReader implements FileReader {
    INSTANCE;

    @Override
    public String readFile(String path) throws IOException {
      return new String(Files.readAllBytes(Paths.get(path)), StandardCharsets.UTF_8);
    }
  }

  private static <T> T checkForNull(T value, String fieldName) throws XdsInitializationException {
    if (value == null) {
      throw new XdsInitializationException(
          "Invalid bootstrap: '" + fieldName + "' does not exist.");
    }
    return value;
  }

}

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Add the named field (given verbatim in the message) to the relevant section of the bootstrap JSON.
2. If the field references a file (certs/CA), confirm the file exists and the path is correct.
3. Compare your bootstrap file against a known-good example for your control plane (Traffic Director, Istio, Envoy SDS).
4. Ensure you're using a bootstrap spec version compatible with your gRPC-xDS library version.

Example fix

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

java.util.Set<String> required = java.util.Set.of("server_uri", "channel_creds");
for (String field : required) {
  if (!serverConfig.containsKey(field) || serverConfig.get(field) == null) {
    throw new IllegalStateException("bootstrap server config missing '" + field + "'");
  }
}
// also verify any referenced cert/CA files exist on disk

When it happens

Trigger: A required bootstrap field — such as "channel_creds", "creds" entries, "type", "certificate" paths, or "ca_certificate_file" referenced from xds_servers — is absent or null. The specific field name appears in the message.

Common situations: TLS-secured xDS configs where credential files were removed or paths renamed; stripped-down bootstrap files missing channel_creds; mismatches between bootstrap spec versions where a field was renamed.

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: missing 'server_uri'
• 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/22ae170c17efd3ae. Report an issue: GitHub.