{"record":{"id":"606a33d42d405c4d","repo":"grpc/grpc-java","slug":"fail-to-read-bootstrap-file","errorCode":null,"errorMessage":"Fail to read bootstrap file","messagePattern":"Fail to read bootstrap file","errorType":"exception","errorClass":"XdsInitializationException","httpStatus":null,"severity":"critical","filePath":"xds/src/main/java/io/grpc/xds/client/BootstrapperImpl.java","lineNumber":96,"sourceCode":"  }\n\n  protected abstract String getJsonContent() throws IOException, XdsInitializationException;\n\n  protected abstract Object getImplSpecificConfig(Map<String, ?> serverConfig, String serverUri)\n      throws XdsInitializationException;\n\n\n  /**\n   * Reads and parses bootstrap config. The config is expected to be in JSON format.\n   */\n  @SuppressWarnings(\"unchecked\")\n  @Override\n  public BootstrapInfo bootstrap() throws XdsInitializationException {\n    String jsonContent;\n    try {\n      jsonContent = getJsonContent();\n    } catch (IOException e) {\n      throw new XdsInitializationException(\"Fail to read bootstrap file\", e);\n    }\n\n    Map<String, ?> rawBootstrap;\n    try {\n      rawBootstrap = (Map<String, ?>) JsonParser.parse(jsonContent);\n    } catch (IOException e) {\n      throw new XdsInitializationException(\"Failed to parse JSON\", e);\n    }\n\n    logger.log(XdsLogLevel.DEBUG, \"Bootstrap configuration:\\n{0}\", rawBootstrap);\n    return bootstrap(rawBootstrap);\n  }\n\n  @Override\n  public BootstrapInfo bootstrap(Map<String, ?> rawData) throws XdsInitializationException {\n    return bootstrapBuilder(rawData).build();\n  }\n","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/client/BootstrapperImpl.java#L78-L114","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set GRPC_XDS_BOOTSTRAP to the absolute path of an existing, readable bootstrap JSON file.","Verify the file exists and is readable by the process user (ls -l / stat the path).","Provide the configuration via the GRPC_XDS_BOOTSTRAP_CONFIG environment variable (inline JSON) instead of a file.","Generate a valid bootstrap file matching the xDS bootstrap v3 spec, including xds_servers with server_uri and channel_creds."],"exampleFix":"// before (no bootstrap file present)\nXdsClient xdsClient = XdsClient.getInstance();\n// after\n// export GRPC_XDS_BOOTSTRAP=/etc/grpc/xds_bootstrap.json\nXdsClient xdsClient = XdsClient.getInstance();","handlingStrategy":"try-catch","validationCode":"String path = System.getenv(\"GRPC_XDS_BOOTSTRAP\");\nif (path != null) {\n  java.io.File f = new java.io.File(path);\n  if (!f.canRead()) throw new IllegalStateException(\n      \"GRPC_XDS_BOOTSTRAP not readable: \" + path);\n}","typeGuard":null,"tryCatchPattern":"try {\n  BootstrapInfo info = bootstrapper.bootstrap();\n} catch (XdsInitializationException e) {\n  // inspect e.getCause() (IOException); verify bootstrap file path/permissions\n}","preventionTips":["Always provision GRPC_XDS_BOOTSTRAP (or GRPC_XDS_BOOTSTRAP_CONFIG) before starting xDS clients.","In containers, mount the bootstrap file and verify readiness before the app process starts.","Check file readability for the runtime user, not just existence."],"tags":["grpc","xds","bootstrap","io","configuration"],"backgroundTag":"file-read-failed","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}