grpc/grpc-java · error · UnsupportedOperationException

Unsupported call - use forPort(int, ServerCredentials)

Error message

Unsupported call - use forPort(int, ServerCredentials)

What it means

XdsServerBuilder.forPort(int) is explicitly annotated @DoNotCall and always throws UnsupportedOperationException. The xDS server requires transport security credentials, so the single-argument forPort overload is intentionally unusable; callers must supply ServerCredentials via forPort(int, ServerCredentials).

Solutions

Replace the call with XdsServerBuilder.forPort(port, serverCredentials), passing credentials such as TlsServerCredentials.create().
If TLS is not desired, explicitly build insecure credentials with InsecureServerCredentials.create() to make the intent clear.
If you truly need a plain server without xDS, use netty's NettyServerBuilder.forPort(port) instead of XdsServerBuilder.

Example fix

// before
ServerBuilder<?> builder = XdsServerBuilder.forPort(8080);
// after
ServerBuilder<?> builder = XdsServerBuilder.forPort(8080,
    TlsServerCredentials.create()); // or InsecureServerCredentials.create()

Defensive patterns

Strategy: validation

Validate before calling

ServerCredentials creds = TlsServerCredentials.create(); // resolve credentials first
assert creds != null : "ServerCredentials required by XdsServerBuilder.forPort";

Prevention

Never call single-argument forPort on XdsServerBuilder; it is @DoNotCall.
Always construct ServerCredentials before building an xDS server.
Use IDE nullness/DoNotCall linting to catch unsupported overloads at compile/edit time.

When it happens

Trigger: Calling XdsServerBuilder.forPort(int port) — the deprecated/unsupported single-argument static factory — instead of the two-argument overload. Every invocation of that method throws immediately.

Common situations: Migrating code written against classic gRPC ServerBuilder.forPort(port) (which works without credentials) to XdsServerBuilder; copy-pasted server bootstrap code; following outdated tutorials from before the gRPC credentials API change (1.37+).

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/48e378363941e78e. Report an issue: GitHub.

Appendix: source

Thrown at xds/src/main/java/io/grpc/xds/XdsServerBuilder.java:133

   * <p>This configurator will subsequently be used to configure any child channels
   * created by that server.
   *
   * @param channelConfigurator the configurator to store in the channel.
   * @return this
   */
  public XdsServerBuilder childChannelConfigurator(ChannelConfigurator channelConfigurator) {
    checkNotNull(channelConfigurator, "channelConfigurator");
    ChannelConfigurator oldConfigurator = this.channelConfigurator;
    this.channelConfigurator = builder -> {
      oldConfigurator.configureChannelBuilder(builder);
      channelConfigurator.configureChannelBuilder(builder);
    };
    return this;
  }

  @DoNotCall("Unsupported. Use forPort(int, ServerCredentials) instead")
  public static ServerBuilder<?> forPort(int port) {
    throw new UnsupportedOperationException(
            "Unsupported call - use forPort(int, ServerCredentials)");
  }

  /** Creates a gRPC server builder for the given port. */
  public static XdsServerBuilder forPort(int port, ServerCredentials serverCredentials) {
    checkNotNull(serverCredentials, "serverCredentials");
    InternalProtocolNegotiator.ServerFactory originalNegotiatorFactory =
            InternalNettyServerCredentials.toNegotiator(serverCredentials);
    ServerCredentials wrappedCredentials = InternalNettyServerCredentials.create(
            new FilterChainMatchingNegotiatorServerFactory(originalNegotiatorFactory));
    NettyServerBuilder nettyDelegate = NettyServerBuilder.forPort(port, wrappedCredentials);
    return new XdsServerBuilder(nettyDelegate, port);
  }

  /** Creates a gRPC server builder for the given address. */
  public static XdsServerBuilder forAddress(
      SocketAddress address, ServerCredentials serverCredentials) {
    checkNotNull(address, "address");

View on GitHub (pinned to 64daddc1f3)