grpc/grpc-java · error · GrpcServiceParseException

Unsupported fallback credentials type for XdsCredentials

Error message

Unsupported fallback credentials type for XdsCredentials

What it means

Thrown by GrpcServiceConfigParser.channelCredsFromProto when unwrapping an XdsCredentials proto whose fallback_credentials field is present but of an unsupported type — the recursive channelCredsFromProto call returns Optional.empty(). XdsChannelCredentials requires a usable fallback credential; without one the credentials block cannot be constructed.

Source

Thrown at xds/src/main/java/io/grpc/xds/GrpcServiceConfigParser.java:218

  private static Optional<ConfiguredChannelCredentials> channelCredsFromProto(Any cred)
      throws GrpcServiceParseException {
    String typeUrl = cred.getTypeUrl();
    try {
      switch (typeUrl) {
        case GOOGLE_DEFAULT_CREDENTIALS_TYPE_URL:
          return Optional
              .of(ConfiguredChannelCredentials.create(GoogleDefaultChannelCredentials.create(),
                  new ProtoChannelCredsConfig(typeUrl, cred)));
        case INSECURE_CREDENTIALS_TYPE_URL:
          return Optional.of(ConfiguredChannelCredentials.create(
              InsecureChannelCredentials.create(), new ProtoChannelCredsConfig(typeUrl, cred)));
        case XDS_CREDENTIALS_TYPE_URL:
          XdsCredentials xdsConfig = cred.unpack(XdsCredentials.class);
          Optional<ConfiguredChannelCredentials> fallbackCreds =
              channelCredsFromProto(xdsConfig.getFallbackCredentials());
          if (!fallbackCreds.isPresent()) {
            throw new GrpcServiceParseException(
                "Unsupported fallback credentials type for XdsCredentials");
          }
          return Optional.of(ConfiguredChannelCredentials.create(
              XdsChannelCredentials.create(fallbackCreds.get().channelCredentials()),
              new ProtoChannelCredsConfig(typeUrl, cred)));
        case LOCAL_CREDENTIALS_TYPE_URL:
          throw new GrpcServiceParseException(
              "LocalCredentials are not supported in grpc-java. "
                  + "See https://github.com/grpc/grpc-java/issues/8928");
        case TLS_CREDENTIALS_TYPE_URL:
          // For this PR, we establish this structural skeleton,
          // but throw an GrpcServiceParseException until the exact stream conversions are
          // merged.
          throw new GrpcServiceParseException(
              "TlsCredentials input stream construction pending.");
        default:
          return Optional.empty();
      }

View on GitHub (pinned to 64daddc1f3)

Solutions

  1. Set fallback_credentials to a supported type (TLS with root certs, or insecure) in the xds_credentials message.
  2. Upgrade grpc-java if the fallback credential type is newer than the client's supported set.
  3. Inspect the sent credentials proto (type_url of the fallback Any) to confirm which case the parser lacks.
  4. If TLS fallback is intended, populate the tls_credentials_type with a valid certificate provider config.

Example fix

// before (xDS resource)
xds_credentials { fallback_credentials { } }
// after
xds_credentials { fallback_credentials { tls_credentials_type { certificate_provider_instance { name: "google_mesh_ca" } } } }
Defensive patterns

Strategy: validation

Validate before calling

// Check fallback credentials are a supported type before accepting the resource
if (cred.getTypeUrl().equals(XDS_CREDENTIALS_TYPE_URL)) {
  XdsCredentials x = cred.unpack(XdsCredentials.class);
  if (!channelCredsFromProto(x.getFallbackCredentials()).isPresent()) {
    throw new IllegalArgumentException("xds credentials need a supported fallback (TLS/insecure)");
  }
}

Try / catch

try {
  Optional<ConfiguredChannelCredentials> creds = channelCredsFromProto(cred);
} catch (GrpcServiceParseException e) {
  if (e.getMessage().contains("fallback credentials")) {
    logger.log(WARNING, "Unsupported fallback creds in xDS resource: " + e.getMessage());
    // fall back to bootstrap-level credentials
  }
}

Prevention

When it happens

Trigger: xDS resource contains credentials with xds_credentials_type whose fallback_credentials is unset in a way that yields empty (unsupported type_url, missing oneof case, or a type not in the parser's switch: TLS, insecure, xds, local), so fallbackCreds.isPresent() is false.

Common situations: Control plane sending fallback credentials of a type grpc-java doesn't implement (e.g. Envoy-only credential types); proto with the fallback oneof left empty while the type implies xds credentials; version skew where newer credential proto types are unknown to the client.

Related errors

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