grpc/grpc-java · error · GrpcServiceParseException

LocalCredentials are not supported in grpc-java. See https:/

Error message

LocalCredentials are not supported in grpc-java. See https://github.com/grpc/grpc-java/issues/8928

What it means

grpc-java's xDS service config parser encountered aLOCAL_CREDENTIALS_TYPE_URL channel-credentials plugin in the xDS bootstrap/config. LocalCredentials (UDS-style/local security) are intentionally unimplemented in grpc-java, tracked upstream in grpc-java issue #8928, so the parser throws GrpcServiceParseException instead of silently misconfiguring the channel.

Source

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

          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();
      }
    } catch (InvalidProtocolBufferException e) {
      throw new GrpcServiceParseException("Failed to parse channel credentials: " + e.getMessage());
    }
  }

  private static ConfiguredChannelCredentials extractChannelCredentials(
      List<Any> channelCredentialPlugins) throws GrpcServiceParseException {

View on GitHub (pinned to 64daddc1f3)

Solutions

Remove the local_credentials plugin from the xDS channel credentials config and use google_default, tls, or xds credentials supported by grpc-java
Regenerate/translate the bootstrap config for Java using only grpc-java-supported credential type URLs
Track/await upstream support in grpc-java issue #8928 if LocalCredentials are a hard requirement

Example fix

// before (bootstrap JSON channel creds plugin)
{"type_url": "type.googleapis.com/grpc.gcp.relay.LocalCredentials"}
// after
{"type_url": "type.googleapis.com/grpc.gcp.relay.TlsCredentials"} // or google_default

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check: skip configs using local_credentials
String typeUrl = plugin.getTypeUrl();
if (typeUrl.contains("LocalCredentials")) {
  throw new IllegalArgumentException("LocalCredentials unsupported in grpc-java");
}

Type guard

boolean isSupportedCredsType(Any cred) {
  String u = cred.getTypeUrl();
  return u != null && !u.contains("LocalCredentials");
}

Try / catch

try {
  XdsChannelCredentialsProvider.parse(config);
} catch (GrpcServiceParseException e) {
  if (e.getMessage().contains("LocalCredentials")) {
    // fall back to google_default credentials
  } else throw e;
}

Prevention

Never reuse bootstrap files written for C++/Python gRPC directly in Java
Keep a Java-specific bootstrap template listing only supported credential types
Watch grpc-java issue #8928 for when LocalCredentials land

When it happens

Trigger: A ChannelCredentialsConfig proto (from xDS bootstrap or server-provided config) contains a channel_credentials_plugins entry whose Any type_url is LOCAL_CREDENTIALS_TYPE_URL; channelCredsFromProto is invoked via fallbackCreds or parsed and hits the LOCAL_CREDENTIALS_TYPE_URL switch case.

Common situations: A bootstrap file or control plane config generated for another gRPC language (e.g. C++ or Python) that supports LocalCredentials is consumed by a grpc-java client; copy-pasted xDS credential configs from non-Java examples.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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