grpc/grpc-java · error · UnsupportedOperationException

call forAddress(AndroidComponentAddress, Context) instead

Error message

call forAddress(AndroidComponentAddress, Context) instead

What it means

BinderChannelBuilder.forAddress(String name, int port) is intentionally unsupported: gRPC Binder channels address Android components, not host:port endpoints. The method is annotated @DoNotCall and always throws UnsupportedOperationException directing you to forAddress(AndroidComponentAddress, Context).

Source

Thrown at binder/src/main/java/io/grpc/binder/BinderChannelBuilder.java:147

   *
   * @param target A target uri which should resolve into an {@link AndroidComponentAddress}
   *     referencing the service to bind to.
   * @param sourceContext the context to bind from (e.g. The current Activity or Application).
   * @param channelCredentials the arbitrary binder specific channel credentials to be used to
   *     establish a binder connection.
   * @return a new builder
   */
  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/10173")
  public static BinderChannelBuilder forTarget(
      String target, Context sourceContext, BinderChannelCredentials channelCredentials) {
    return new BinderChannelBuilder(
        null, checkNotNull(target, "target"), sourceContext, channelCredentials);
  }

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

  /** Always fails. Call {@link #forAddress(AndroidComponentAddress, Context)} instead. */
  @DoNotCall("Unsupported. Use forTarget(String, Context) instead")
  public static BinderChannelBuilder forTarget(String target) {
    throw new UnsupportedOperationException(
        "call forAddress(AndroidComponentAddress, Context) instead");
  }

  private final ManagedChannelImplBuilder managedChannelImplBuilder;
  private final BinderClientTransportFactory.Builder transportFactoryBuilder;

  private boolean strictLifecycleManagement;

  private BinderChannelBuilder(
      @Nullable AndroidComponentAddress directAddress,
      @Nullable String target,

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Use BinderChannelBuilder.forAddress(AndroidComponentAddress, Context) targeting the server component
2. If you need host:port channels, use the standard ManagedChannelBuilder instead of the binder transport
3. Route Android component addressing via AndroidComponentAddress.forComponent(ComponentName) or the binder-specific factories

Example fix

// before
BinderChannelBuilder b = BinderChannelBuilder.forAddress("com.example/.Svc", 8080);
// after
BinderChannelBuilder b = BinderChannelBuilder.forAddress(
    AndroidComponentAddress.forComponent(new ComponentName("com.example", "com.example.Svc")),
    context);

if (address instanceof AndroidComponentAddress) {
  builder = BinderChannelBuilder.forAddress((AndroidComponentAddress) address, context);
} else {
  builder = ManagedChannelBuilder.forAddress(host, port);
}

static boolean supportsBinderTransport(SocketAddress addr) {
  return addr instanceof AndroidComponentAddress;
}

try {
  return BinderChannelBuilder.forAddress(componentAddr, context).build();
} catch (UnsupportedOperationException e) {
  throw new IllegalStateException("Binder channels need AndroidComponentAddress", e);
}

When it happens

Trigger: Calling BinderChannelBuilder.forAddress(host, port) — typically ported code using the generic ManagedChannelBuilder API pattern on the binder transport.

Common situations: Refactoring a normal gRPC channel to BinderChannelBuilder and reusing forAddress("10.0.0.1", 50051); copy-pasted builder code from an INET-based client.

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 forAddress() instead
• TLS not supported in BinderServer
• Unsupported operation getPort()
• The transport factory is closed.
• call forAddress() instead

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