grpc/grpc-java · critical · XdsInitializationException

Invalid bootstrap: server ${serverUri} 'channel_creds' requi

Error message

Invalid bootstrap: server ${serverUri} 'channel_creds' required

What it means

GrpcBootstrapperImpl.getChannelCredentials reads the channel_creds array of an xds_servers entry; if the key is missing or the list is empty, it throws XdsInitializationException "Invalid bootstrap: server <serverUri> 'channel_creds' required". Every management server in the bootstrap must declare at least one credential type so the client can authenticate the xDS channel.

Source

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

  }

  static synchronized BootstrapInfo defaultBootstrap() throws XdsInitializationException {
    if (defaultBootstrap == null) {
      if (defaultBootstrapOverride == null) {
        defaultBootstrap = new GrpcBootstrapperImpl().bootstrap();
      } else {
        defaultBootstrap = new GrpcBootstrapperImpl().bootstrap(defaultBootstrapOverride);
      }
    }
    return defaultBootstrap;
  }

  private static ConfiguredChannelCredentials getChannelCredentials(Map<String, ?> serverConfig,
                                                                  String serverUri)
      throws XdsInitializationException {
    List<?> rawChannelCredsList = JsonUtil.getList(serverConfig, "channel_creds");
    if (rawChannelCredsList == null || rawChannelCredsList.isEmpty()) {
      throw new XdsInitializationException(
          "Invalid bootstrap: server " + serverUri + " 'channel_creds' required");
    }
    ConfiguredChannelCredentials credentials =
        parseChannelCredentials(JsonUtil.checkObjectList(rawChannelCredsList), serverUri);
    if (credentials == null) {
      throw new XdsInitializationException(
          "Server " + serverUri + ": no supported channel credentials found");
    }
    return credentials;
  }

  @Nullable
  private static ConfiguredChannelCredentials parseChannelCredentials(List<Map<String, ?>> jsonList,
          String serverUri)
      throws XdsInitializationException {
    for (Map<String, ?> channelCreds : jsonList) {
      String type = JsonUtil.getString(channelCreds, "type");
      if (type == null) {

View on GitHub (pinned to 64daddc1f3)

Solutions

  1. Add a channel_creds array to each xds_servers entry, e.g. [{"type": "google_default"}] or [{"type": "insecure"}] for plaintext testing.
  2. Confirm the credential type string is one the client supports (insecure, google_default, tls) and that parseChannelCredentials returns non-null.
  3. Validate your bootstrap JSON against the gRPC xDS bootstrap schema before deploying.
  4. If channel_creds is present but still failing, check the next error path ('No valid credentials found') for unsupported types.

Example fix

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

Strategy: validation

Validate before calling

for (Object s : (List<?>) boot.get("xds_servers")) {
  Map<?, ?> server = (Map<?, ?>) s;
  Object creds = server.get("channel_creds");
  if (!(creds instanceof List<?>) || ((List<?>) creds).isEmpty()) {
    throw new IllegalArgumentException("channel_creds missing for server " + server.get("server_uri"));
  }
}

Try / catch

try { /* init xDS */ } catch (XdsInitializationException e) { if (e.getMessage().contains("'channel_creds' required")) { log.error("Add channel_creds to xds_servers entry"); } }

Prevention

When it happens

Trigger: Bootstrap JSON whose xds_servers[i] object lacks channel_creds or has "channel_creds": [] — thrown while building the ConfiguredChannel during bootstrap parsing.

Common situations: Hand-written bootstrap omitting channel_creds; config generators dropping the field; copying an example that only shows server_uri; empty array left after stripping credentials for local testing.

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

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