grpc/grpc-java · error · IllegalArgumentException

${result.error}

Error message

${result.error}

What it means

NettyServerBuilder.forAddress() validates the provided ServerCredentials through ProtocolNegotiators.from(creds). If the credentials are null or of an unsupported type, the resulting result.error string is thrown as an IllegalArgumentException. This fails fast before any server resources are created.

Source

Thrown at netty/src/main/java/io/grpc/netty/NettyServerBuilder.java:167

   * Creates a server builder configured with the given {@link SocketAddress}.
   *
   * @param address the socket address on which the server is to be bound.
   * @return the server builder
   */
  public static NettyServerBuilder forAddress(SocketAddress address) {
    return new NettyServerBuilder(address);
  }

  /**
   * Creates a server builder configured with the given {@link SocketAddress}.
   *
   * @param address the socket address on which the server is to be bound.
   * @return the server builder
   */
  public static NettyServerBuilder forAddress(SocketAddress address, ServerCredentials creds) {
    ProtocolNegotiators.FromServerCredentialsResult result = ProtocolNegotiators.from(creds);
    if (result.error != null) {
      throw new IllegalArgumentException(result.error);
    }
    return new NettyServerBuilder(address, result.negotiator);
  }

  private final class NettyClientTransportServersBuilder implements ClientTransportServersBuilder {
    @Override
    public InternalServer buildClientTransportServers(
        List<? extends ServerStreamTracer.Factory> streamTracerFactories,
        MetricRecorder metricRecorder) {
      return buildTransportServers(streamTracerFactories, metricRecorder);
    }
  }

  private NettyServerBuilder(SocketAddress address) {
    serverImplBuilder = new ServerImplBuilder(new NettyClientTransportServersBuilder());
    this.listenAddresses.add(address);
    this.protocolNegotiatorFactory = ProtocolNegotiators.serverPlaintextFactory();
    this.freezeProtocolNegotiatorFactory = false;

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Use supported ServerCredentials: TlsServerCredentials.create() or InsecureServerCredentials.create().
2. Read the thrown message — it is produced by ProtocolNegotiators.from() and names the offending credentials.
3. Do not pass ChannelCredentials to a server builder; build server-side credentials instead.
4. Align grpc-netty and grpc-api versions (grpc-bom) to avoid class skew.

Example fix

// before
Server server = NettyServerBuilder.forAddress(port, channelCreds) // wrong credentials type
    .build();
// after
Server server = NettyServerBuilder.forAddress(new InetSocketAddress(port),
    TlsServerCredentials.newBuilder().build()).build();

if (creds == null || creds instanceof io.grpc.InsecureServerCredentials || creds instanceof io.grpc.TlsServerCredentials) {
  // supported by grpc-netty server builder
}

static boolean isNettySupportedServerCredentials(ServerCredentials c) {
  return c instanceof TlsServerCredentials || c instanceof InsecureServerCredentials;
}

try {
  Server s = NettyServerBuilder.forAddress(addr, creds).build();
} catch (IllegalArgumentException e) {
  // message comes from ProtocolNegotiators.from(); swap to TlsServerCredentials/InsecureServerCredentials
}

When it happens

Trigger: Calling NettyServerBuilder.forAddress(addr, creds) with null ServerCredentials, an unrecognized ServerCredentials subclass, or TlsServerCredentials whose conversion produces an error — the error string from ProtocolNegotiators.from() is thrown verbatim.

Common situations: Passing credentials intended for the client side (ChannelCredentials) instead of ServerCredentials; custom ServerCredentials implementations the Netty transport cannot handle; version/classpath mismatch between grpc-api and grpc-netty.

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

• Unexpected error converting ServerCredentials to Netty SslCo
• Invalid initial window size: ${newWindowSize}
• No ALTS context information found
• Can't set TLS settings for ALTS
• Not implemented

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