{"record":{"id":"4a17e302f21856c4","repo":"grpc/grpc-java","slug":"cannot-load-epolldomainsocketchannel","errorCode":null,"errorMessage":"Cannot load EpollDomainSocketChannel","messagePattern":"Cannot load EpollDomainSocketChannel","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"netty/src/main/java/io/grpc/netty/Utils.java","lineNumber":411,"sourceCode":"  // Must call when epoll is available\n  private static Class<? extends Channel> epollChannelType() {\n    try {\n      Class<? extends Channel> channelType = Class\n          .forName(\"io.netty.channel.epoll.EpollSocketChannel\").asSubclass(Channel.class);\n      return channelType;\n    } catch (ClassNotFoundException e) {\n      throw new RuntimeException(\"Cannot load EpollSocketChannel\", e);\n    }\n  }\n\n  // Must call when epoll is available\n  private static Class<? extends Channel> epollDomainSocketChannelType() {\n    try {\n      Class<? extends Channel> channelType = Class\n          .forName(\"io.netty.channel.epoll.EpollDomainSocketChannel\").asSubclass(Channel.class);\n      return channelType;\n    } catch (ClassNotFoundException e) {\n      throw new RuntimeException(\"Cannot load EpollDomainSocketChannel\", e);\n    }\n  }\n\n  // Must call when epoll is available\n  private static Constructor<? extends EventLoopGroup> epollEventLoopGroupConstructor() {\n    try {\n      return Class\n          .forName(\"io.netty.channel.epoll.EpollEventLoopGroup\").asSubclass(EventLoopGroup.class)\n          .getConstructor(Integer.TYPE, ThreadFactory.class);\n    } catch (ClassNotFoundException e) {\n      throw new RuntimeException(\"Cannot load EpollEventLoopGroup\", e);\n    } catch (NoSuchMethodException e) {\n      throw new RuntimeException(\"EpollEventLoopGroup constructor not found\", e);\n    }\n  }\n\n  // Must call when epoll is available\n  private static Class<? extends ServerChannel> epollServerChannelType() {","sourceCodeStart":393,"sourceCodeEnd":429,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/netty/src/main/java/io/grpc/netty/Utils.java#L393-L429","documentation":"gRPC-netty loads io.netty.channel.epoll.EpollDomainSocketChannel reflectively to support Unix domain socket channels. This RuntimeException wraps the ClassNotFoundException raised when the epoll transport classes are not on the classpath. The caller is expected to invoke this only when epoll is available, so failing here means the epoll dependency is missing despite that assumption.","triggerScenarios":"Resolving the domain socket channel type via Utils.epollDomainSocketChannelType() (used when the target address is a unix:/// UDS address) while io.netty:netty-transport-native-epoll is absent from the runtime classpath.","commonSituations":"Connecting to a server over a Unix domain socket (NettyChannelBuilder.forAddress(UnixDomainSocketAddress...) or 'unix:' target) on Linux without the netty-transport-native-epoll dependency; slimmed container images or shaded jars that omit the epoll classes/natives.","solutions":["Add io.netty:netty-transport-native-epoll with the appropriate linux classifier to the runtime classpath","Confirm the UDS address is only used on Linux with epoll support present; otherwise fall back to TCP/loopback","Align Netty versions (dependency:tree) so io.netty.channel.epoll.EpollDomainSocketChannel exists at the expected version","Check packaging rules (shade excludes, jlink, image slimming) are not stripping io.netty.channel.epoll.* or the native .so"],"exampleFix":"// before\nManagedChannel ch = NettyChannelBuilder.forAddress(\"unix\", \"/var/run/srv.sock\").build(); // throws if epoll missing\n\n// after — ensure classpath has:\n// implementation 'io.netty:netty-transport-native-epoll:4.1.x:linux-x86_64'\nManagedChannel ch = NettyChannelBuilder.forAddress(\"unix\", \"/var/run/srv.sock\")\n    .channelType(io.grpc.netty.Utils.EPOLL_DOMAIN_SOCKET_CHANNEL_TYPE)\n    .build();","handlingStrategy":"fallback","validationCode":"static boolean epollDomainSocketSupported() {\n  try {\n    Class.forName(\"io.netty.channel.epoll.EpollDomainSocketChannel\");\n    return true;\n  } catch (ClassNotFoundException e) {\n    return false;\n  }\n}","typeGuard":"static boolean canUseUnixDomainSocket() {\n  return \"Linux\".equalsIgnoreCase(System.getProperty(\"os.name\")) && epollDomainSocketSupported();\n}","tryCatchPattern":"try {\n  return NettyChannelBuilder.forAddress(\"unix\", sockPath);\n} catch (RuntimeException e) {\n  if (e.getCause() instanceof ClassNotFoundException) {\n    return NettyChannelBuilder.forAddress(\"localhost\", tcpPort); // fall back to TCP\n  }\n  throw e;\n}","preventionTips":["Ship netty-transport-native-epoll when using unix: targets","Probe for EpollDomainSocketChannel before choosing UDS transport","Fall back to TCP loopback on non-Linux or when epoll natives are missing","Keep Netty version consistent with grpc-netty","Test UDS channels in the same packaging used in production"],"tags":["netty","grpc","unix-domain-socket","classpath","epoll"],"backgroundTag":"class-not-found","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}