grpc/grpc-java · error · RuntimeException

Failed to create OkHttpChannelBuilder

Error message

Failed to create OkHttpChannelBuilder

What it means

forPath() reflects on the OkHttpChannelBuilder to call socketFactory(SocketFactory) on it. An IllegalAccessException means the reflection call was blocked by Java access rules — the OkHttpChannelBuilder class is visible by name but the JVM denied invoking the method, typically due to restrictive class loading or modular access controls. The method wraps it in a RuntimeException with this message.

Source

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

      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);
    } catch (NoSuchMethodException e) {
      throw new RuntimeException("Failed to create OkHttpChannelBuilder", e);
    } catch (InvocationTargetException e) {
      throw new RuntimeException("Failed to create OkHttpChannelBuilder", e);
    }
  }

  private UdsChannelBuilder() {}
}

View on GitHub (pinned to 64daddc1f3)

Solutions

  1. Unwrap the cause in the RuntimeException to confirm which reflection step failed and verify OkHttpChannelBuilder is loaded by the app classloader.
  2. Ensure grpc-okhttp is a normal compile/runtime dependency of the main app module, not a separate plugin classloader.
  3. Remove ProGuard rules that make OkHttpChannelBuilder members inaccessible.
  4. As a diagnostic, call Class.forName("io.grpc.okhttp.OkHttpChannelBuilder") yourself and log its ClassLoader.
Defensive patterns

Strategy: try-catch

Validate before calling

Class<?> c = Class.forName("io.grpc.okhttp.OkHttpChannelBuilder");
if (c.getMethod("socketFactory", SocketFactory.class) == null) { /* unreachable, but surfaces access errors early */ }

Try / catch

try {
  channel = UdsChannelBuilder.forPath(path, ns).build();
} catch (RuntimeException e) {
  Throwable cause = e.getCause();
  if (cause instanceof IllegalAccessException) { /* classloader/access issue: log loader of OkHttpChannelBuilder */ }
  throw e;
}

Prevention

When it happens

Trigger: Calling UdsChannelBuilder.forPath() when OkHttpChannelBuilder is on the classpath but the reflective OKHTTP_CHANNEL_BUILDER_CLASS.getMethod("socketFactory", SocketFactory.class).invoke(...) is denied by access control (IllegalAccessException).

Common situations: Multi-classloader environments (custom Android classloaders, dynamic feature modules) where the class was loaded in a restrictive loader; exotic runtime classloader setups rarely seen in standard Android apps.

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/4814fe43ec66c27d. Report an issue: GitHub.