{"record":{"id":"323bfeb7343b39ee","repo":"grpc/grpc-java","slug":"clienttransportserversbuilder-is-required-use-a-c","errorCode":null,"errorMessage":"ClientTransportServersBuilder is required, use a constructor","messagePattern":"ClientTransportServersBuilder is required, use a constructor","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/grpc/internal/ServerImplBuilder.java","lineNumber":66,"sourceCode":"import java.util.ArrayList;\nimport java.util.Collections;\nimport java.util.List;\nimport java.util.concurrent.Executor;\nimport java.util.concurrent.TimeUnit;\nimport java.util.logging.Level;\nimport java.util.logging.Logger;\nimport javax.annotation.Nullable;\n\n/**\n * Default builder for {@link io.grpc.Server} instances, for usage in Transport implementations.\n */\npublic final class ServerImplBuilder extends ServerBuilder<ServerImplBuilder> {\n\n  private static final Logger log = Logger.getLogger(ServerImplBuilder.class.getName());\n\n  @DoNotCall(\"ClientTransportServersBuilder is required, use a constructor\")\n  public static ServerBuilder<?> forPort(int port) {\n    throw new UnsupportedOperationException(\n        \"ClientTransportServersBuilder is required, use a constructor\");\n  }\n\n  // defaults\n  private static final ObjectPool<? extends Executor> DEFAULT_EXECUTOR_POOL =\n      SharedResourcePool.forResource(GrpcUtil.SHARED_CHANNEL_EXECUTOR);\n  private static final HandlerRegistry DEFAULT_FALLBACK_REGISTRY = new DefaultFallbackRegistry();\n  private static final DecompressorRegistry DEFAULT_DECOMPRESSOR_REGISTRY =\n      DecompressorRegistry.getDefaultInstance();\n  private static final CompressorRegistry DEFAULT_COMPRESSOR_REGISTRY =\n      CompressorRegistry.getDefaultInstance();\n  private static final long DEFAULT_HANDSHAKE_TIMEOUT_MILLIS = TimeUnit.SECONDS.toMillis(120);\n\n  // mutable state\n  final InternalHandlerRegistry.Builder registryBuilder =\n      new InternalHandlerRegistry.Builder();\n  final List<ServerTransportFilter> transportFilters = new ArrayList<>();\n  final List<ServerInterceptor> interceptors = new ArrayList<>();","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/core/src/main/java/io/grpc/internal/ServerImplBuilder.java#L48-L84","documentation":"ServerImplBuilder is the base class for concrete server builders (e.g. NettyServerBuilder). Its static inherited forPort(int) method cannot construct a transport-agnostic server, so it's annotated @DoNotCall and always throws UnsupportedOperationException, instructing users to use a concrete constructor.","triggerScenarios":"Calling ServerBuilder.forPort(port) generically (e.g. via reflection or generic code paths) when the resolved builder is ServerImplBuilder rather than a concrete transport builder like NettyServerBuilder.forPort().","commonSituations":"Using ServerBuilder.forPort() without grpc-netty(-shaded) on the classpath so the service loader finds no provider and falls back to ServerImplBuilder; generic framework code calling ServerBuilder.forPort directly.","solutions":["Use a concrete transport builder: NettyServerBuilder.forPort(port) or NettyServerBuilder.forPort with grpc-netty dependency","Add the transport dependency (grpc-netty or grpc-netty-shaded) so ServerBuilder.forPort can find a provider via META-INF/services","Replace generic ServerBuilder.forPort calls in framework code with the transport-specific constructor"],"exampleFix":"// before\nServer server = ServerBuilder.forPort(8080).build(); // no transport provider\n// after\nServer server = NettyServerBuilder.forPort(8080).build();","handlingStrategy":"type-guard","validationCode":"if (b instanceof ServerImplBuilder) { throw new IllegalStateException(\"No transport provider; add grpc-netty and use NettyServerBuilder\"); }","typeGuard":"static boolean hasTransportProvider(ServerBuilder<?> b) { return !(b instanceof io.grpc.internal.ServerImplBuilder); }","tryCatchPattern":"try { server = ServerBuilder.forPort(port).build(); } catch (UnsupportedOperationException e) { if (e.getMessage().contains(\"ClientTransportServersBuilder is required\")) { server = NettyServerBuilder.forPort(port).build(); } else throw e; }","preventionTips":["Always construct servers with a concrete builder (NettyServerBuilder)","Ensure a transport artifact (grpc-netty/-shaded) is on the runtime classpath","Don't rely on ServerBuilder.forPort service-loading in shaded environments"],"tags":["grpc","server-builder","unsupported-operation","missing-dependency"],"backgroundTag":"unsupported-operation","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}