grpc/grpc-java · critical · ProviderNotFoundException

No functional channel service provider found. Try adding a d

Error message

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

What it means

grpc-java locates a transport implementation (e.g. netty or okhttp) via java.util.ServiceLoader at runtime. When no transport jar is on the classpath, ManagedChannelProvider.provider() finds no registered provider and throws ProviderNotFoundException. The API module alone cannot create channels; a concrete transport artifact must be present.

Source

Thrown at api/src/main/java/io/grpc/ManagedChannelProvider.java:45

 * automatic discovery, the implementation must have a zero-argument constructor and include
 * a resource named {@code META-INF/services/io.grpc.ManagedChannelProvider} 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 ManagedChannelProvider {
  /**
   * Returns the ClassLoader-wide default channel.
   *
   * @throws ProviderNotFoundException if no provider is available
   */
  public static ManagedChannelProvider provider() {
    ManagedChannelProvider provider = ManagedChannelRegistry.getDefaultRegistry().provider();
    if (provider == null) {
      throw new ProviderNotFoundException("No functional channel service provider found. "
          + "Try adding a dependency on the grpc-okhttp, 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.
   */

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Add a transport dependency, e.g. implementation 'io.grpc:grpc-netty-shaded:1.x.y' (Android: grpc-okhttp)
2. Run mvn dependency:tree / gradle dependencies and confirm a grpc transport artifact is present and not excluded
3. If packaging a fat/shaded jar, ensure META-INF/services/io.grpc.ManagedChannelProvider files are merged (ServicesResourceTransformer in shade plugin)
4. Check for duplicate grpc-api versions causing provider registration mismatch via dependency management

Example fix

// before
dependencies {
    implementation 'io.grpc:grpc-api:1.62.2'
}
// after
dependencies {
    implementation 'io.grpc:grpc-netty-shaded:1.62.2'
}

boolean hasTransport;
try {
  Class.forName("io.grpc.netty.shaded.io.grpc.netty.NettyChannelProvider");
  hasTransport = true;
} catch (ClassNotFoundException e) {
  hasTransport = false; // also try okhttp provider class before failing
}
if (!hasTransport) throw new IllegalStateException("Add grpc-netty-shaded or grpc-okhttp to the classpath");

static boolean hasChannelProvider() {
  return ManagedChannelRegistry.getDefaultRegistry().providers() != null
      && !ManagedChannelRegistry.getDefaultRegistry().providers().isEmpty();
}

try {
  ManagedChannel channel = ManagedChannelBuilder.forAddress(host, port).build();
} catch (ProviderNotFoundException e) {
  throw new IllegalStateException("Missing grpc transport dependency: add grpc-netty-shaded/grpc-okhttp", e);
}

When it happens

Trigger: Calling ManagedChannelBuilder.forAddress(...) / forTarget(...), or ManagedChannelProvider.provider() / ManagedChannelRegistry.newChannelBuilder(...), when the classpath contains grpc-api but no transport provider (grpc-netty, grpc-netty-shaded, or grpc-okhttp) registered via META-INF/services.

Common situations: Adding io.grpc:grpc-api or a thin client library as a direct dependency without a transport; dependency exclusions stripping grpc-netty; building an Android app without grpc-okhttp; shaded/relocated classpaths where the service file is missing; using a wrong artifact like grpc-core only.

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

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

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