{"record":{"id":"6a70c3578ca34850","repo":"grpc/grpc-java","slug":"no-functional-server-found-try-adding-a-dependenc-6a70c3","errorCode":null,"errorMessage":"No functional server found. Try adding a dependency on the grpc-netty, grpc-netty-shaded, or grpc-okhttp artifact","messagePattern":"No functional server found\\. Try adding a dependency on the grpc-netty, grpc-netty-shaded, or grpc-okhttp artifact","errorType":"exception","errorClass":"ProviderNotFoundException","httpStatus":null,"severity":"critical","filePath":"api/src/main/java/io/grpc/ServerRegistry.java","lineNumber":142,"sourceCode":"\n  @VisibleForTesting\n  static List<Class<?>> getHardCodedClasses() {\n    // Class.forName(String) is used to remove the need for ProGuard configuration. Note that\n    // ProGuard does not detect usages of Class.forName(String, boolean, ClassLoader):\n    // https://sourceforge.net/p/proguard/bugs/418/\n    List<Class<?>> list = new ArrayList<>();\n    try {\n      list.add(Class.forName(\"io.grpc.okhttp.OkHttpServerProvider\"));\n    } catch (ClassNotFoundException e) {\n      logger.log(Level.FINE, \"Unable to find OkHttpServerProvider\", e);\n    }\n    return Collections.unmodifiableList(list);\n  }\n\n  ServerBuilder<?> newServerBuilderForPort(int port, ServerCredentials creds) {\n    List<ServerProvider> providers = providers();\n    if (providers.isEmpty()) {\n      throw new ProviderNotFoundException(\"No functional server found. \"\n          + \"Try adding a dependency on the grpc-netty, grpc-netty-shaded, or grpc-okhttp \"\n          + \"artifact\");\n    }\n    StringBuilder error = new StringBuilder();\n    for (ServerProvider provider : providers()) {\n      ServerProvider.NewServerBuilderResult result\n          = provider.newServerBuilderForPort(port, creds);\n      if (result.getServerBuilder() != null) {\n        return result.getServerBuilder();\n      }\n      error.append(\"; \");\n      error.append(provider.getClass().getName());\n      error.append(\": \");\n      error.append(result.getError());\n    }\n    throw new ProviderNotFoundException(error.substring(2));\n  }\n","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/api/src/main/java/io/grpc/ServerRegistry.java#L124-L160","documentation":"ServerRegistry.newServerBuilderForPort iterates registered ServerProviders and throws ProviderNotFoundException when the provider list is empty, telling you to add grpc-netty, grpc-netty-shaded, or grpc-okhttp. Like the ServerProvider path, this is the 'no transport implementation on the classpath' error surfaced through the ServerBuilder.forPort(int, ServerCredentials) API (grpc 1.38+ with TLS-aware credentials).","triggerScenarios":"Calling ServerBuilder.forPort(port, serverCredentials) or ServerRegistry.newServerBuilderForPort with zero registered providers — i.e. no transport artifact on the runtime classpath, or its META-INF/services/io.grpc.ServerProvider entry stripped.","commonSituations":"New projects with only grpc-api/grpc-core; shaded or minimized jars losing the service file; GraalVM native images without service registration; build tool exclusions dropping grpc-netty.","solutions":["Add io.grpc:grpc-netty, grpc-netty-shaded, or grpc-okhttp to the runtime classpath","Verify META-INF/services/io.grpc.ServerProvider exists in the transport jar and is packaged in your fat jar","Inspect dependency trees for exclusions/provided scope incorrectly applied to the transport artifact","In native-image builds, add the provider to the service-loader configuration"],"exampleFix":"// before\nServerBuilder<?> sb = ServerBuilder.forPort(8443, InsecureServerCredentials.create()); // throws\n// after (gradle)\n// implementation 'io.grpc:grpc-netty-shaded:1.60.0'\nServerBuilder<?> sb = ServerBuilder.forPort(8443, InsecureServerCredentials.create());","handlingStrategy":"try-catch","validationCode":"// preflight: is any provider registered before calling forPort(port, creds)?\njava.util.Iterator<ServerProvider> it =\n    java.util.ServiceLoader.load(ServerProvider.class).iterator();\nif (!it.hasNext()) {\n  throw new IllegalStateException(\"no ServerProvider: add grpc-netty/grpc-okhttp\");\n}","typeGuard":"static boolean canBuildServerForPort() {\n  return java.util.ServiceLoader.load(ServerProvider.class).iterator().hasNext();\n}","tryCatchPattern":"try {\n  ServerBuilder<?> b = ServerBuilder.forPort(port, creds);\n} catch (ProviderNotFoundException e) {\n  logger.error(\"No transport provider registered: {}\", e.getMessage());\n  throw new IllegalStateException(\"Add grpc-netty, grpc-netty-shaded, or grpc-okhttp\", e);\n}","preventionTips":["Check the fat jar contains META-INF/services/io.grpc.ServerProvider","Avoid proguard/graal configs that strip ServiceLoader files without registering them","Use grpc-netty-shaded to avoid netty version conflicts that block provider loading","Validate the classpath in CI with a server build/start smoke test"],"tags":["grpc","classpath","missing-dependency","provider-not-found"],"backgroundTag":"missing-dependency","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"}