grpc/grpc-java · error · UnsupportedOperationException

Use Grpc.newServerBuilderForPort() instead

Error message

Use Grpc.newServerBuilderForPort() instead

What it means

OkHttpServerProvider.builderForPort(int) is the provider SPI hook for credentials-less server builder creation; in the OkHttp provider it is intentionally never implemented and always throws UnsupportedOperationException because all server creation must go through the ServerCredentials-based Grpc.newServerBuilderForPort path.

Source

Thrown at okhttp/src/main/java/io/grpc/okhttp/OkHttpServerProvider.java:41

/** Provider for {@link OkHttpServerBuilder} instances. */
@Internal
public final class OkHttpServerProvider extends ServerProvider {

  @Override
  protected boolean isAvailable() {
    return true;
  }

  @Override
  protected int priority() {
    // Use a priority less than Netty since builderForPort() always throws.
    return 4;
  }

  @Override
  protected OkHttpServerBuilder builderForPort(int port) {
    throw new UnsupportedOperationException("Use Grpc.newServerBuilderForPort() instead");
  }

  @Override
  protected NewServerBuilderResult newServerBuilderForPort(int port, ServerCredentials creds) {
    OkHttpServerBuilder.HandshakerSocketFactoryResult result =
        OkHttpServerBuilder.handshakerSocketFactoryFrom(creds);
    if (result.error != null) {
      return NewServerBuilderResult.error(result.error);
    }
    return NewServerBuilderResult.serverBuilder(
        new OkHttpServerBuilder(new InetSocketAddress(port), result.factory));
  }
}

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Use Grpc.newServerBuilderForPort(port, creds) instead of provider.builderForPort(port)
2. Align grpc-core and grpc-okhttp versions (same release train) so the credentials-based SPI is used
3. Remove code paths that construct servers via ServerProvider.provider().builderForPort

Example fix

// before
OkHttpServerBuilder b = provider.builderForPort(8080);
// after
OkHttpServerBuilder b = (OkHttpServerBuilder) Grpc.newServerBuilderForPort(8080, InsecureServerCredentials.getInsecureInstance());

// Use the supported API directly
ServerBuilder<?> b = Grpc.newServerBuilderForPort(port, creds);

When it happens

Trigger: Calling this protected provider method directly, or an environment where grpc-core's ServerProvider dispatch falls back to the deprecated builderForPort path (e.g. old grpc-core calling ServerProvider.builderForPort(int)).

Common situations: Mixed grpc-core/grpc-okhttp versions where core still uses the legacy SPI; tests instantiating OkHttpServerProvider and invoking builderForPort directly.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• Use forPort(int, ServerCredentials) instead
• Can't set TLS settings for ALTS
• Not implemented
• Not implemented
• Not implemented

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