grpc/grpc-java · error · UnsupportedOperationException

call forName() instead

Error message

call forName() instead

What it means

InProcessChannelBuilder.forAddress(String, int) is intentionally unsupported because in-process transport has no network address; channels are identified by name. The two-argument overload always throws UnsupportedOperationException and is marked @DoNotCall.

Solutions

1. Use InProcessChannelBuilder.forName(target) where target matches the name given to InProcessServerBuilder.forName(...).
2. Use InProcessChannelBuilder.forName(InProcessServerBuilder.generateName()) when creating a server without a fixed name.
3. If an address-based channel is truly needed, use NettyChannelBuilder/OkHttpChannelBuilder instead.

Example fix

// before
ManagedChannel ch = InProcessChannelBuilder.forAddress("localhost", 8080).build();
// after
ManagedChannel ch = InProcessChannelBuilder.forName("my-inprocess-server").build();

if (useInProcess && target.contains(":")) throw new IllegalArgumentException("in-process channels must use forName(target), not forAddress(host, port)");

When it happens

Trigger: Calling InProcessChannelBuilder.forAddress(host, port) instead of InProcessChannelBuilder.forName(serverName).

Common situations: Reusing generic channel-builder factory code across netty/inprocess transports; converting an app to in-process transport while keeping address-based setup.

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/629548a0856ebe8e. Report an issue: GitHub.

Appendix: source

Thrown at inprocess/src/main/java/io/grpc/inprocess/InProcessChannelBuilder.java:91

    return new InProcessChannelBuilder(null, checkNotNull(target, "target"));
  }

  /**
   * Create a channel builder that will connect to the server referenced by the given address.
   *
   * @param address the address of the server to connect to
   * @return a new builder
   */
  public static InProcessChannelBuilder forAddress(SocketAddress address) {
    return new InProcessChannelBuilder(checkNotNull(address, "address"), null);
  }

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

  private final ManagedChannelImplBuilder managedChannelImplBuilder;
  private ScheduledExecutorService scheduledExecutorService;
  private int maxInboundMetadataSize = Integer.MAX_VALUE;
  private boolean transportIncludeStatusCause = false;
  private long assumedMessageSize = -1;

  private InProcessChannelBuilder(@Nullable SocketAddress directAddress, @Nullable String target) {

    final class InProcessChannelTransportFactoryBuilder implements ClientTransportFactoryBuilder {
      @Override
      public ClientTransportFactory buildClientTransportFactory() {
        return buildTransportFactory();
      }
    }

    if (directAddress != null) {

View on GitHub (pinned to 64daddc1f3)