{"record":{"id":"31113ea3ad52ec63","repo":"grpc/grpc-java","slug":"no-functional-server-found-try-adding-a-dependenc","errorCode":null,"errorMessage":"No functional server found. Try adding a dependency on the grpc-netty or grpc-netty-shaded artifact","messagePattern":"No functional server found\\. Try adding a dependency on the grpc-netty or grpc-netty-shaded artifact","errorType":"exception","errorClass":"ProviderNotFoundException","httpStatus":null,"severity":"critical","filePath":"api/src/main/java/io/grpc/ServerProvider.java","lineNumber":44,"sourceCode":" * automatic discovery, the implementation must have a zero-argument constructor and include\n * a resource named {@code META-INF/services/io.grpc.ServerProvider} in their JAR. The\n * file's contents should be the implementation's class name.\n *\n * <p>Implementations <em>should not</em> throw. If they do, it may interrupt class loading. If\n * exceptions may reasonably occur for implementation-specific reasons, implementations should\n * generally handle the exception gracefully and return {@code false} from {@link #isAvailable()}.\n */\n@Internal\npublic abstract class ServerProvider {\n  /**\n   * Returns the ClassLoader-wide default server.\n   *\n   * @throws ProviderNotFoundException if no provider is available\n   */\n  public static ServerProvider provider() {\n    ServerProvider provider = ServerRegistry.getDefaultRegistry().provider();\n    if (provider == null) {\n      throw new ProviderNotFoundException(\"No functional server found. \"\n          + \"Try adding a dependency on the grpc-netty or grpc-netty-shaded artifact\");\n    }\n    return provider;\n  }\n\n  /**\n   * Whether this provider is available for use, taking the current environment into consideration.\n   * If {@code false}, no other methods are safe to be called.\n   */\n  protected abstract boolean isAvailable();\n\n  /**\n   * A priority, from 0 to 10 that this provider should be used, taking the current environment into\n   * consideration. 5 should be considered the default, and then tweaked based on environment\n   * detection. A priority of 0 does not imply that the provider wouldn't work; just that it should\n   * be last in line.\n   */\n  protected abstract int priority();","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/api/src/main/java/io/grpc/ServerProvider.java#L26-L62","documentation":"ServerProvider.provider() looks up a registered ServerProvider via ServerRegistry; if none is available it throws ProviderNotFoundException with this message. gRPC's api module defines only the SPI — an actual server implementation comes from grpc-netty, grpc-netty-shaded, or grpc-okhttp, discovered through META-INF/services registration. Without one, no server can be built.","triggerScenarios":"Calling ServerBuilder.forPort(...) (or ServerProvider.provider()) when the classpath contains only grpc-api and no transport implementation artifact, or the provider's services file is excluded from the jar (e.g. shaded/minimized builds, Graal native image, android proguard stripping META-INF/services).","commonSituations":"Forgetting to add grpc-netty to a new project; dependency exclusions removing the transport; classpath conflicts where ServerRegistry cannot see the provider; native-image builds missing service-loader registration.","solutions":["Add io.grpc:grpc-netty (or grpc-netty-shaded/grpc-okhttp) as a runtime dependency","Check the jar for META-INF/services/io.grpc.ServerProvider; if stripped, restore service-loader entries or disable jar minimization","Run `mvn dependency:tree` (or gradle dependencies) to confirm the transport artifact is present and not excluded","For native images, register the ServerProvider service or add reflection/service config"],"exampleFix":"// before (pom.xml: only api)\n<dependency>\n  <groupId>io.grpc</groupId>\n  <artifactId>grpc-api</artifactId>\n</dependency>\n// after\n<dependency>\n  <groupId>io.grpc</groupId>\n  <artifactId>grpc-api</artifactId>\n</dependency>\n<dependency>\n  <groupId>io.grpc</groupId>\n  <artifactId>grpc-netty-shaded</artifactId>\n</dependency>","handlingStrategy":"try-catch","validationCode":"// fail fast at startup if no transport provider is registered\nif (ServerProvider.provider() == null) { // would itself throw; wrap:\n}\ntry {\n  ServerProvider.provider();\n} catch (ProviderNotFoundException e) {\n  throw new IllegalStateException(\"Add io.grpc:grpc-netty-shaded dependency\", e);\n}","typeGuard":"static boolean hasTransportProvider() {\n  try {\n    java.util.ServiceLoader.load(io.grpc.ServerProvider.class).iterator().hasNext();\n    return java.util.ServiceLoader.load(io.grpc.ServerProvider.class).iterator().hasNext();\n  } catch (Throwable t) { return false; }\n}","tryCatchPattern":"try {\n  ServerBuilder.forPort(8080).build().start();\n} catch (ProviderNotFoundException e) {\n  logger.error(\"No grpc transport on classpath: {}\", e.getMessage());\n  throw new IllegalStateException(\"Add grpc-netty-shaded to dependencies\", e);\n}","preventionTips":["Always declare grpc-netty/grpc-netty-shaded/grpc-okhttp in runtime dependencies","Don't exclude META-INF/services when building shaded or minimized jars","Run `mvn dependency:tree` to verify the transport artifact is not 'provided' or excluded","For GraalVM native images, include the service-loader entry for io.grpc.ServerProvider"],"tags":["grpc","classpath","missing-dependency","server-provider"],"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"}