grpc/grpc-java · error · IllegalArgumentException

${result.error}

Error message

${result.error}

What it means

NettyChannelBuilder.forAddress(SocketAddress, ChannelCredentials) validates the credentials up front via ProtocolNegotiators.from(); if the credentials type cannot produce a Netty protocol negotiator, the resulting error string is thrown as IllegalArgumentException before any channel is built.

Source

Thrown at netty/src/main/java/io/grpc/netty/NettyChannelBuilder.java:154

   * noticing changes to DNS. If an unresolved InetSocketAddress is passed in, then it will remain
   * unresolved.
   */
  public static NettyChannelBuilder forAddress(SocketAddress serverAddress) {
    return new NettyChannelBuilder(serverAddress);
  }

  /**
   * Creates a new builder with the given server address. This factory method is primarily intended
   * for using Netty Channel types other than SocketChannel.
   * {@link #forAddress(String, int, ChannelCredentials)} should generally be preferred over this
   * method, since that API permits delaying DNS lookups and noticing changes to DNS. If an
   * unresolved InetSocketAddress is passed in, then it will remain unresolved.
   */
  public static NettyChannelBuilder forAddress(SocketAddress serverAddress,
      ChannelCredentials creds) {
    FromChannelCredentialsResult result = ProtocolNegotiators.from(creds);
    if (result.error != null) {
      throw new IllegalArgumentException(result.error);
    }
    return new NettyChannelBuilder(serverAddress, creds, result.callCredentials, result.negotiator);
  }

  /**
   * Creates a new builder with the given host and port.
   */
  public static NettyChannelBuilder forAddress(String host, int port) {
    return forTarget(GrpcUtil.authorityFromHostAndPort(host, port));
  }

  /**
   * Creates a new builder with the given host and port.
   */
  public static NettyChannelBuilder forAddress(String host, int port, ChannelCredentials creds) {
    return forTarget(GrpcUtil.authorityFromHostAndPort(host, port), creds);
  }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Use TlsChannelCredentials or InsecureChannelCredentials, which Netty supports
2. Obtain credentials from NettyChannelCredentials.builder() for Netty-specific features
3. Check that the creds argument was not accidentally swapped with the target/address

Example fix

// before
NettyChannelBuilder.forAddress(addr, inProcessCreds);
// after
NettyChannelBuilder.forAddress(addr, TlsChannelCredentials.newBuilder().trustManager(caCerts).build());

if (!(creds instanceof TlsChannelCredentials) && !(creds instanceof InsecureChannelCredentials)) { throw new IllegalArgumentException("NettyChannelBuilder requires TLS or insecure credentials"); }

boolean usableByNetty(ChannelCredentials c) { return c instanceof TlsChannelCredentials || c instanceof InsecureChannelCredentials; }

try { builder = NettyChannelBuilder.forAddress(addr, creds); } catch (IllegalArgumentException e) { log.error("Incompatible credentials for Netty: " + e.getMessage()); throw e; }

When it happens

Trigger: Calling NettyChannelBuilder.forAddress(addr, creds) with credentials the Netty transport does not support (e.g. credentials created for a different transport implementation).

Common situations: Passing in-process or alternative-transport ChannelCredentials to a Netty builder; custom ChannelCredentials; accidentally swapping channel/target pairs in forAddress overloads.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• ${result.error}
• ${result.error}
• Unsupported provider: ${provider}
• TsiHandshakeHandler encountered exception
• At least one credential is required

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