grpc/grpc-java · error · UnsupportedOperationException

call forName() instead

Error message

call forName() instead

What it means

InProcessServerBuilder.forPort(int) is intentionally unsupported because in-process servers have no ports; they are addressed by name. The method always throws UnsupportedOperationException and is marked @DoNotCall.

Solutions

1. Use InProcessServerBuilder.forName(name) with a stable or generated name (generateName()).
2. Pass the same name to InProcessChannelBuilder.forName(...) on the client side.
3. Use NettyServerBuilder.forPort(port) if a real bound port is needed.

Example fix

// before
Server s = InProcessServerBuilder.forPort(8080).addService(...).build();
// after
Server s = InProcessServerBuilder.forName("my-inprocess-server").addService(...).build();

if (serverBuilder instanceof InProcessServerBuilder && portConfigured) throw new IllegalArgumentException("in-process servers use forName(name), not forPort(port)");

When it happens

Trigger: Calling InProcessServerBuilder.forPort(port) instead of InProcessServerBuilder.forName(serverName).

Common situations: Adapting generic server-builder code (written for netty port binding) to in-process transport; config-driven port numbers applied to in-process servers.

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

• call forName() instead
• AnonymousInProcessSocketAddress is not serializable
• call forAddress(AndroidComponentAddress, Context) instead
• call forAddress() instead
• call forAddress() instead

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

Appendix: source

Thrown at inprocess/src/main/java/io/grpc/inprocess/InProcessServerBuilder.java:102

  public static InProcessServerBuilder forName(String name) {
    return forAddress(new InProcessSocketAddress(checkNotNull(name, "name")));
  }

  /**
   * Create a server builder which listens on the given address.
   * @param listenAddress The SocketAddress this server will listen on.
   * @return a new builder
   */
  public static InProcessServerBuilder forAddress(SocketAddress listenAddress) {
    return new InProcessServerBuilder(listenAddress);
  }

  /**
   * Always fails.  Call {@link #forName} instead.
   */
  @DoNotCall("Unsupported. Use forName() instead")
  public static InProcessServerBuilder forPort(int port) {
    throw new UnsupportedOperationException("call forName() instead");
  }

  /**
   * Generates a new server name that is unique each time.
   */
  public static String generateName() {
    return UUID.randomUUID().toString();
  }

  private final ServerImplBuilder serverImplBuilder;
  final SocketAddress listenAddress;
  int maxInboundMetadataSize = Integer.MAX_VALUE;
  ObjectPool<ScheduledExecutorService> schedulerPool =
      SharedResourcePool.forResource(GrpcUtil.TIMER_SERVICE);

  private InProcessServerBuilder(SocketAddress listenAddress) {
    this.listenAddress = checkNotNull(listenAddress, "listenAddress");

View on GitHub (pinned to 64daddc1f3)