grpc/grpc-java · error · ServiceConfigurationError

Provider ${rawClass} could not be instantiated ${t}

Error message

Provider ${rawClass} could not be instantiated ${t}

What it means

ServiceProviders.createForHardCoded() reflectively instantiates a hard-coded provider class and wraps any Throwable (other than ClassNotFoundException/ClassCastException which are skipped) into a ServiceConfigurationError. This means the provider class was found but its construction failed — bad constructor, initialization exception, missing dependencies, etc.

Source

Thrown at api/src/main/java/io/grpc/ServiceProviders.java:150

      }
      list.add(t);
    }
    return list;
  }

  private static <T> T createForHardCoded(Class<T> klass, Class<?> rawClass) {
    try {
      return rawClass.asSubclass(klass).getConstructor().newInstance();
    } catch (ClassCastException ex) {
      // Tools like Proguard that perform obfuscation rewrite strings only when the class they
      // reference is known, as otherwise they wouldn't know its new name. This means some
      // hard-coded Class.forNames() won't be rewritten. This can cause ClassCastException at
      // runtime if the class ends up appearing on the classpath but that class is part of a
      // separate copy of grpc. With tools like Maven Shade Plugin the class wouldn't be found at
      // all and so would be skipped. We want to skip in this case as well.
      return null;
    } catch (Throwable t) {
      throw new ServiceConfigurationError(
          String.format("Provider %s could not be instantiated %s", rawClass.getName(), t), t);
    }
  }

  /**
   * An interface that allows us to get priority information about a provider.
   */
  public interface PriorityAccessor<T> {
    /**
     * Checks this provider is available for use, taking the current environment into consideration.
     * If {@code false}, no other methods are safe to be called.
     */
    boolean isAvailable(T provider);

    /**
     * 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

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Fix the classpath so the provider and grpc-core versions match (e.g. align grpc-netty-shaded with grpc-core)
2. Check the wrapped cause `t` in the message for the actual constructor failure and fix that dependency
3. Remove duplicate/stale gRPC jars so only one copy exists
4. Explicitly configure the desired provider via io.grpc.PROVIDER_SELECTOR or -Dio.grpc... provider properties, or disable broken providers via the configurable disabling mechanism

Example fix

// before (classpath has grpc-netty 1.40 with grpc-core 1.60)
// ServiceConfigurationError: Provider io.grpc.netty.NettyChannelProvider could not be instantiated java.lang.NoSuchMethodError
// after: align versions
// gradle:
implementation 'io.grpc:grpc-netty-shaded:1.60.0'
implementation 'io.grpc:grpc-core:1.60.0'

try (var _ = Class.forName(providerClassName, true, loader)) { /* provider loadable */ }

try {
  provider = ServiceProviders.createForHardCoded(cls, args, loader);
} catch (ServiceConfigurationError e) {
  logger.warn("Provider unavailable, falling back: " + e.getCause(), e);
  provider = null; // skip and try next provider
}

When it happens

Trigger: A hard-coded provider class name is loadable but Provider.newInstance() throws: no-arg constructor missing, static initializer fails, constructor throws due to missing runtime dependency, or the loaded class is from an incompatible gRPC copy causing a cast failure inside the constructor path.

Common situations: Shaded/fat jars with multiple gRPC copies on the classpath; a provider (e.g. netty-shaded, okhttp) version mismatched with grpc-core; missing optional dependencies needed by the provider at construction time; security manager blocking instantiation.

Related errors

• Unable to load OkHttpChannelProvider
• OkHttpChannelBuilder not found on the classpath
• No functional channel service provider found. Try adding a d
• No functional channel service provider found. Try adding a d
• 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/c6a530b8f5fb9467. Report an issue: GitHub.