grpc/grpc-java · critical · XdsInitializationException

Fail to read bootstrap file

Error message

Fail to read bootstrap file

What it means

BootstrapperImpl.bootstrap() reads the xDS bootstrap file (from GRPC_XDS_BOOTSTRAP env var or the default gRPC bootstrap location) and wraps any IOException from that read into XdsInitializationException("Fail to read bootstrap file"). The xDS client cannot start without this configuration.

Source

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

  }

  protected abstract String getJsonContent() throws IOException, XdsInitializationException;

  protected abstract Object getImplSpecificConfig(Map<String, ?> serverConfig, String serverUri)
      throws XdsInitializationException;


  /**
   * Reads and parses bootstrap config. The config is expected to be in JSON format.
   */
  @SuppressWarnings("unchecked")
  @Override
  public BootstrapInfo bootstrap() throws XdsInitializationException {
    String jsonContent;
    try {
      jsonContent = getJsonContent();
    } catch (IOException e) {
      throw new XdsInitializationException("Fail to read bootstrap file", e);
    }

    Map<String, ?> rawBootstrap;
    try {
      rawBootstrap = (Map<String, ?>) JsonParser.parse(jsonContent);
    } catch (IOException e) {
      throw new XdsInitializationException("Failed to parse JSON", e);
    }

    logger.log(XdsLogLevel.DEBUG, "Bootstrap configuration:\n{0}", rawBootstrap);
    return bootstrap(rawBootstrap);
  }

  @Override
  public BootstrapInfo bootstrap(Map<String, ?> rawData) throws XdsInitializationException {
    return bootstrapBuilder(rawData).build();
  }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Set GRPC_XDS_BOOTSTRAP to the absolute path of an existing, readable bootstrap JSON file.
2. Verify the file exists and is readable by the process user (ls -l / stat the path).
3. Provide the configuration via the GRPC_XDS_BOOTSTRAP_CONFIG environment variable (inline JSON) instead of a file.
4. Generate a valid bootstrap file matching the xDS bootstrap v3 spec, including xds_servers with server_uri and channel_creds.

Example fix

// before (no bootstrap file present)
XdsClient xdsClient = XdsClient.getInstance();
// after
// export GRPC_XDS_BOOTSTRAP=/etc/grpc/xds_bootstrap.json
XdsClient xdsClient = XdsClient.getInstance();

String path = System.getenv("GRPC_XDS_BOOTSTRAP");
if (path != null) {
  java.io.File f = new java.io.File(path);
  if (!f.canRead()) throw new IllegalStateException(
      "GRPC_XDS_BOOTSTRAP not readable: " + path);
}

try {
  BootstrapInfo info = bootstrapper.bootstrap();
} catch (XdsInitializationException e) {
  // inspect e.getCause() (IOException); verify bootstrap file path/permissions
}

When it happens

Trigger: GRPC_XDS_BOOTSTRAP points to a nonexistent file or unreadable path; the default bootstrap file location is empty/absent; filesystem permission problems; the path is a directory.

Common situations: Deploying a workload with xDS enabled but forgetting to mount/create the bootstrap file; Kubernetes sidecar setups where the bootstrap file isn't ready yet; wrong file path in GRPC_XDS_BOOTSTRAP; running locally without any bootstrap configuration.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• CertificateProvider instance name '${certInstanceName}' not
• ca_certificate_provider_instance name '${rootCaInstanceName}
• Failed to parse JSON
• Invalid bootstrap: 'xds_servers' does not exist.
• client_listener_resource_name_template: '${clientListnerTemp

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