grpc/grpc-java · critical · XdsInitializationException

Failed to parse JSON

Error message

Failed to parse JSON

What it means

After reading the bootstrap file successfully, BootstrapperImpl.bootstrap() parses its contents with JsonParser.parse. If parsing throws IOException (malformed JSON), it is wrapped in XdsInitializationException("Failed to parse JSON"). The bootstrap file must be valid JSON per the xDS bootstrap spec.

Source

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

  /**
   * 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();
  }

  protected BootstrapInfo.Builder bootstrapBuilder(Map<String, ?> rawData)
      throws XdsInitializationException {
    BootstrapInfo.Builder builder = BootstrapInfo.builder();

    List<?> rawServerConfigs = JsonUtil.getList(rawData, "xds_servers");
    if (rawServerConfigs == null) {
      throw new XdsInitializationException("Invalid bootstrap: 'xds_servers' does not exist.");

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Validate the bootstrap file with a JSON parser (e.g. `jq . $GRPC_XDS_BOOTSTRAP`) and fix syntax errors.
2. Check that config templating actually rendered all placeholders before the process starts.
3. Regenerate the bootstrap file from your control plane / service mesh tooling rather than hand-editing.
4. Confirm the file is plain UTF-8 text, not YAML or binary.

Example fix

// before: bootstrap file contains YAML or unrendered {{ .Values }}
// after: valid JSON bootstrap file
{
  "xds_servers": [{ "server_uri": "dns:///xds.example.com:443",
                     "channel_creds": [{"type": "google_default"}] }]
}

String content = new String(java.nio.file.Files.readAllBytes(
    java.nio.file.Paths.get(System.getenv("GRPC_XDS_BOOTSTRAP"))),
    java.nio.charset.StandardCharsets.UTF_8);
try (var parser = new com.google.gson.JsonParser()) {
  parser.parseString(content); // throws if invalid JSON
}

try {
  BootstrapInfo info = bootstrapper.bootstrap();
} catch (XdsInitializationException e) {
  if (e.getMessage().contains("Failed to parse JSON")) {
    // validate/repair bootstrap JSON before retrying
  }
}

When it happens

Trigger: The file referenced by GRPC_XDS_BOOTSTRAP (or the default bootstrap path) contains invalid JSON: truncation, YAML instead of JSON, comments, trailing commas, template placeholders left unsubstituted, or non-UTF8/binary content.

Common situations: Hand-edited bootstrap files with syntax errors; config-management tools rendering partial templates (e.g. unexpanded {{ }}); files copied with encoding corruption; YAML bootstrap examples pasted as .json.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Unable to parse custom LB config JSON
• Custom LB config does not contain a JSON object
• CertificateProvider instance name '${certInstanceName}' not
• ca_certificate_provider_instance name '${rootCaInstanceName}
• Fail to read bootstrap file

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