grpc/grpc-java · critical · XdsInitializationException

Cannot find bootstrap configuration Environment variables se

Error message

Cannot find bootstrap configuration
Environment variables searched:
- GRPC_XDS_BOOTSTRAP
- GRPC_XDS_BOOTSTRAP_CONFIG

Java System Properties searched:
- io.grpc.xds.bootstrap
- io.grpc.xds.bootstrapConfig

What it means

GrpcBootstrapperImpl.getJsonContent locates bootstrap JSON from the file given by GRPC_XDS_BOOTSTRAP (or system property io.grpc.xds.bootstrap) or the inline GRPC_XDS_BOOTSTRAP_CONFIG (io.grpc.xds.bootstrapConfig). If none of these sources yields content, it throws XdsInitializationException listing every location searched. The xDS client cannot start without bootstrap data.

Source

Thrown at xds/src/main/java/io/grpc/xds/GrpcBootstrapperImpl.java:90

   *   <li>Environment variable value of "GRPC_XDS_BOOTSTRAP_CONFIG"</li>
   *   <li>Java System Property value of "io.grpc.xds.bootstrapConfig"</li>
   * </ol>
   */
  @Override
  protected String getJsonContent() throws XdsInitializationException, IOException {
    String jsonContent;
    String filePath =
        bootstrapPathFromEnvVar != null ? bootstrapPathFromEnvVar : bootstrapPathFromSysProp;
    if (filePath != null) {
      logger.log(XdsLogger.XdsLogLevel.INFO, "Reading bootstrap file from {0}", filePath);
      jsonContent = reader.readFile(filePath);
      logger.log(XdsLogger.XdsLogLevel.INFO, "Reading bootstrap from " + filePath);
    } else {
      jsonContent = bootstrapConfigFromEnvVar != null
          ? bootstrapConfigFromEnvVar : bootstrapConfigFromSysProp;
    }
    if (jsonContent == null) {
      throw new XdsInitializationException(
          "Cannot find bootstrap configuration\n"
              + "Environment variables searched:\n"
              + "- " + BOOTSTRAP_PATH_SYS_ENV_VAR + "\n"
              + "- " + BOOTSTRAP_CONFIG_SYS_ENV_VAR + "\n\n"
              + "Java System Properties searched:\n"
              + "- " + BOOTSTRAP_PATH_SYS_PROPERTY + "\n"
              + "- " + BOOTSTRAP_CONFIG_SYS_PROPERTY + "\n\n");
    }

    return jsonContent;
  }

  @Override
  protected Object getImplSpecificConfig(Map<String, ?> serverConfig, String serverUri)
      throws XdsInitializationException {
    ConfiguredChannelCredentials configuredChannel = getChannelCredentials(serverConfig, serverUri);
    return configuredChannel != null ? configuredChannel.channelCredentials() : null;
  }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Set GRPC_XDS_BOOTSTRAP_CONFIG (or system property io.grpc.xds.bootstrapConfig) with inline bootstrap JSON.
2. Or set GRPC_XDS_BOOTSTRAP (io.grpc.xds.bootstrap) to a readable bootstrap file path and verify the file exists at that exact path.
3. Enable XdsLogger INFO logs to see which bootstrap path was attempted and why it wasn't used.
4. For GKE with CSM/metadata servers, ensure the environment actually provides the bootstrap (Workload/Mesh CA setup) or supply it manually.

Example fix

// before — starting the channel with no bootstrap anywhere
ManagedChannel.forTarget("xds://...").build();
// after
// export GRPC_XDS_BOOTSTRAP=/etc/grpc/bootstrap.json  (file exists and is readable)
ManagedChannel.forTarget("xds://...").build();

// run before creating an xds:// channel
String path = System.getenv("GRPC_XDS_BOOTSTRAP");
String inline = System.getenv("GRPC_XDS_BOOTSTRAP_CONFIG");
if (inline == null && (path == null || !java.nio.file.Files.isReadable(java.nio.file.Path.of(path)))) {
  throw new IllegalStateException("No xDS bootstrap: set GRPC_XDS_BOOTSTRAP or GRPC_XDS_BOOTSTRAP_CONFIG");
}

try { /* init xDS */ } catch (XdsInitializationException e) { if (e.getMessage().startsWith("Cannot find bootstrap configuration")) { log.error("Set GRPC_XDS_BOOTSTRAP/GRPC_XDS_BOOTSTRAP_CONFIG"); } }

When it happens

Trigger: Initializing any xDS-enabled channel/resolver when: the bootstrap env vars and system properties are unset, the referenced file path doesn't exist or is unreadable (in which case parsing falls through), and no inline config is provided.

Common situations: Forgetting to set GRPC_XDS_BOOTSTRAP in the container/pod; file path typo or missing volume mount; property set with -D on the wrong JVM; tests running without bootstrap setup.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Invalid bootstrap: 'xds_servers' is empty
• Invalid bootstrap: server ${serverUri} 'channel_creds' requi
• Server ${serverUri}: no supported channel credentials found
• Invalid bootstrap: server ${serverUri} with 'channel_creds'
• Invalid allowed_grpc_services config for ${targetUri}

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