grpc/grpc-java · error · UnsupportedOperationException

OkHttpChannelBuilder not found on the classpath

Error message

OkHttpChannelBuilder not found on the classpath

What it means

UdsChannelBuilder.forPath() builds UDS channels by reflectively loading io.grpc.okhttp.OkHttpChannelBuilder and injecting a UdsSocketFactory into it. If the grpc-okhttp artifact is not on the classpath, the static Class.forName lookup in findOkHttp() returns null and forPath() throws this UnsupportedOperationException immediately. The UDS transport simply cannot work without the OkHttp transport implementation present.

Source

Thrown at android/src/main/java/io/grpc/android/UdsChannelBuilder.java:69

  @SuppressWarnings("rawtypes")
  private static Class<? extends ManagedChannelBuilder> findOkHttp() {
    try {
      return Class.forName("io.grpc.okhttp.OkHttpChannelBuilder")
          .asSubclass(ManagedChannelBuilder.class);
    } catch (ClassNotFoundException e) {
      return null;
    }
  }

  /**
   * Returns a channel to the UDS endpoint specified by the file-path.
   *
   * @param path unix file system path to use for Unix Domain Socket.
   * @param namespace the type of the namespace that the path belongs to.
   */
  public static ManagedChannelBuilder<?> forPath(String path, Namespace namespace) {
    if (OKHTTP_CHANNEL_BUILDER_CLASS == null) {
      throw new UnsupportedOperationException("OkHttpChannelBuilder not found on the classpath");
    }
    try {
      // Target 'dns:///127.0.0.1' is unused, but necessary as an argument for OkHttpChannelBuilder.
      // An IP address is used instead of localhost to avoid a DNS lookup (see #11442). This should
      // work even if IPv4 is unavailable, as the DNS resolver doesn't need working IPv4 to parse an
      // IPv4 address. Unavailable IPv4 fails when we connect(), not at resolution time.
      // TLS is unsupported because Conscrypt assumes the platform Socket implementation to improve
      // performance by using the file descriptor directly.
      Object o = OKHTTP_CHANNEL_BUILDER_CLASS
          .getMethod("forTarget", String.class, ChannelCredentials.class)
          .invoke(null, "dns:///127.0.0.1", InsecureChannelCredentials.create());
      ManagedChannelBuilder<?> builder = OKHTTP_CHANNEL_BUILDER_CLASS.cast(o);
      OKHTTP_CHANNEL_BUILDER_CLASS
          .getMethod("socketFactory", SocketFactory.class)
          .invoke(builder, new UdsSocketFactory(path, namespace));
      return builder.proxyDetector(GrpcUtil.NOOP_PROXY_DETECTOR);
    } catch (IllegalAccessException e) {
      throw new RuntimeException("Failed to create OkHttpChannelBuilder", e);

View on GitHub (pinned to 64daddc1f3)

Solutions

  1. Add the grpc-okhttp dependency (implementation 'io.grpc:grpc-okhttp:<matching grpc version>') to the app module.
  2. Check ProGuard/R8 keep rules so io.grpc.okhttp.** is not stripped from the release build.
  3. Verify the grpc-okhttp version matches the rest of the grpc-* artifacts to avoid mixed-version classpath issues.
  4. If UDS support is not needed, use a regular ManagedChannelBuilder instead of UdsChannelBuilder.forPath().

Example fix

// before
dependencies {
    implementation 'io.grpc:grpc-android:1.50.0'
}
// after
dependencies {
    implementation 'io.grpc:grpc-android:1.50.0'
    implementation 'io.grpc:grpc-okhttp:1.50.0'
}
Defensive patterns

Strategy: fallback

Validate before calling

try {
  Class.forName("io.grpc.okhttp.OkHttpChannelBuilder");
} catch (ClassNotFoundException e) {
  throw new IllegalStateException("grpc-okhttp missing from classpath; add io.grpc:grpc-okhttp");
}

Try / catch

try {
  channel = UdsChannelBuilder.forPath(path, Namespace.FILESYSTEM).build();
} catch (UnsupportedOperationException e) {
  // grpc-okhttp not on classpath: fall back to TCP channel
  channel = ManagedChannelBuilder.forAddress(host, port).usePlaintext().build();
}

Prevention

When it happens

Trigger: Calling UdsChannelBuilder.forPath(path, namespace) at runtime in an app whose dependency set does not include io.grpc:grpc-okhttp, so the static initializer found no OkHttpChannelBuilder class.

Common situations: Android apps that added grpc-android but ProGuard/R8 stripped or the build excluded grpc-okhttp; projects that switched to another transport (e.g. Netty on server, or cronet) and assumed UdsChannelBuilder was transport-agnostic; missing transitive dependency after dependency tree pruning.

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

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