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 or grpc-netty-shaded artifact

What it means

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.

Source

Thrown at api/src/main/java/io/grpc/ServerProvider.java:44

 * automatic discovery, the implementation must have a zero-argument constructor and include
 * a resource named {@code META-INF/services/io.grpc.ServerProvider} in their JAR. The
 * file's contents should be the implementation's class name.
 *
 * <p>Implementations <em>should not</em> throw. If they do, it may interrupt class loading. If
 * exceptions may reasonably occur for implementation-specific reasons, implementations should
 * generally handle the exception gracefully and return {@code false} from {@link #isAvailable()}.
 */
@Internal
public abstract class ServerProvider {
  /**
   * Returns the ClassLoader-wide default server.
   *
   * @throws ProviderNotFoundException if no provider is available
   */
  public static ServerProvider provider() {
    ServerProvider provider = ServerRegistry.getDefaultRegistry().provider();
    if (provider == null) {
      throw new ProviderNotFoundException("No functional server found. "
          + "Try adding a dependency on the grpc-netty or grpc-netty-shaded artifact");
    }
    return provider;
  }

  /**
   * Whether this provider is available for use, taking the current environment into consideration.
   * If {@code false}, no other methods are safe to be called.
   */
  protected abstract boolean isAvailable();

  /**
   * A priority, from 0 to 10 that this provider should be used, taking the current environment into
   * consideration. 5 should be considered the default, and then tweaked based on environment
   * detection. A priority of 0 does not imply that the provider wouldn't work; just that it should
   * be last in line.
   */
  protected abstract int priority();

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Add io.grpc:grpc-netty (or grpc-netty-shaded/grpc-okhttp) as a runtime dependency
2. Check the jar for META-INF/services/io.grpc.ServerProvider; if stripped, restore service-loader entries or disable jar minimization
3. Run `mvn dependency:tree` (or gradle dependencies) to confirm the transport artifact is present and not excluded
4. For native images, register the ServerProvider service or add reflection/service config

Example fix

// before (pom.xml: only api)
<dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-api</artifactId>
</dependency>
// after
<dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-api</artifactId>
</dependency>
<dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-netty-shaded</artifactId>
</dependency>

// fail fast at startup if no transport provider is registered
if (ServerProvider.provider() == null) { // would itself throw; wrap:
}
try {
  ServerProvider.provider();
} catch (ProviderNotFoundException e) {
  throw new IllegalStateException("Add io.grpc:grpc-netty-shaded dependency", e);
}

static boolean hasTransportProvider() {
  try {
    java.util.ServiceLoader.load(io.grpc.ServerProvider.class).iterator().hasNext();
    return java.util.ServiceLoader.load(io.grpc.ServerProvider.class).iterator().hasNext();
  } catch (Throwable t) { return false; }
}

try {
  ServerBuilder.forPort(8080).build().start();
} catch (ProviderNotFoundException e) {
  logger.error("No grpc transport on classpath: {}", e.getMessage());
  throw new IllegalStateException("Add grpc-netty-shaded to dependencies", e);
}

When it happens

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

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

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/31113ea3ad52ec63. Report an issue: GitHub.