grpc/grpc-java · critical · ProviderNotFoundException

No functional server found. Try adding a dependency on the g

Error message

No functional server found. Try adding a dependency on the grpc-netty, grpc-netty-shaded, or grpc-okhttp artifact

What it means

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).

Source

Thrown at api/src/main/java/io/grpc/ServerRegistry.java:142

  @VisibleForTesting
  static List<Class<?>> getHardCodedClasses() {
    // Class.forName(String) is used to remove the need for ProGuard configuration. Note that
    // ProGuard does not detect usages of Class.forName(String, boolean, ClassLoader):
    // https://sourceforge.net/p/proguard/bugs/418/
    List<Class<?>> list = new ArrayList<>();
    try {
      list.add(Class.forName("io.grpc.okhttp.OkHttpServerProvider"));
    } catch (ClassNotFoundException e) {
      logger.log(Level.FINE, "Unable to find OkHttpServerProvider", e);
    }
    return Collections.unmodifiableList(list);
  }

  ServerBuilder<?> newServerBuilderForPort(int port, ServerCredentials creds) {
    List<ServerProvider> providers = providers();
    if (providers.isEmpty()) {
      throw new ProviderNotFoundException("No functional server found. "
          + "Try adding a dependency on the grpc-netty, grpc-netty-shaded, or grpc-okhttp "
          + "artifact");
    }
    StringBuilder error = new StringBuilder();
    for (ServerProvider provider : providers()) {
      ServerProvider.NewServerBuilderResult result
          = provider.newServerBuilderForPort(port, creds);
      if (result.getServerBuilder() != null) {
        return result.getServerBuilder();
      }
      error.append("; ");
      error.append(provider.getClass().getName());
      error.append(": ");
      error.append(result.getError());
    }
    throw new ProviderNotFoundException(error.substring(2));
  }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Add io.grpc:grpc-netty, grpc-netty-shaded, or grpc-okhttp to the runtime classpath
2. Verify META-INF/services/io.grpc.ServerProvider exists in the transport jar and is packaged in your fat jar
3. Inspect dependency trees for exclusions/provided scope incorrectly applied to the transport artifact
4. In native-image builds, add the provider to the service-loader configuration

Example fix

// before
ServerBuilder<?> sb = ServerBuilder.forPort(8443, InsecureServerCredentials.create()); // throws
// after (gradle)
// implementation 'io.grpc:grpc-netty-shaded:1.60.0'
ServerBuilder<?> sb = ServerBuilder.forPort(8443, InsecureServerCredentials.create());

// preflight: is any provider registered before calling forPort(port, creds)?
java.util.Iterator<ServerProvider> it =
    java.util.ServiceLoader.load(ServerProvider.class).iterator();
if (!it.hasNext()) {
  throw new IllegalStateException("no ServerProvider: add grpc-netty/grpc-okhttp");
}

static boolean canBuildServerForPort() {
  return java.util.ServiceLoader.load(ServerProvider.class).iterator().hasNext();
}

try {
  ServerBuilder<?> b = ServerBuilder.forPort(port, creds);
} catch (ProviderNotFoundException e) {
  logger.error("No transport provider registered: {}", e.getMessage());
  throw new IllegalStateException("Add grpc-netty, grpc-netty-shaded, or grpc-okhttp", e);
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• OkHttpChannelBuilder not found on the classpath
• No functional server found. Try adding a dependency on the g
• Unable to load OkHttpChannelProvider
• No functional channel service provider found. Try adding a d
• No functional channel service provider found. Try adding a d

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