{"record":{"id":"490dcc22718e356e","repo":"grpc/grpc-java","slug":"epolleventloopgroup-constructor-not-found","errorCode":null,"errorMessage":"EpollEventLoopGroup constructor not found","messagePattern":"EpollEventLoopGroup constructor not found","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"netty/src/main/java/io/grpc/netty/Utils.java","lineNumber":424,"sourceCode":"    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() {\n    try {\n      Class<? extends ServerChannel> serverSocketChannel =\n          Class\n              .forName(\"io.netty.channel.epoll.EpollServerSocketChannel\")\n              .asSubclass(ServerChannel.class);\n      return serverSocketChannel;\n    } catch (ClassNotFoundException e) {\n      throw new RuntimeException(\"Cannot load EpollServerSocketChannel\", e);\n    }\n  }\n\n  private static EventLoopGroup createEpollEventLoopGroup(\n      int parallelism,","sourceCodeStart":406,"sourceCodeEnd":442,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/netty/src/main/java/io/grpc/netty/Utils.java#L406-L442","documentation":"gRPC-netty found the EpollEventLoopGroup class but could not locate the expected Constructor(Class/int, ThreadFactory) via getConstructor. This RuntimeException wraps NoSuchMethodException, indicating an incompatible Netty version where the epoll event loop group no longer exposes that constructor signature.","triggerScenarios":"Calling Utils.epollEventLoopGroupConstructor() (during epoll transport setup for a channel or server) against a Netty version where io.netty.channel.epoll.EpollEventLoopGroup lacks the (Integer, ThreadFactory) constructor — typically due to a Netty upgrade or mixed Netty jar versions.","commonSituations":"Upgrading Netty (or a framework that pulls a newer/older Netty) while grpc-netty still expects the 4.1-era constructor; multiple Netty versions on the classpath so the resolved class differs from the one grpc-netty was compiled against; shaded/relocated epoll classes.","solutions":["Align the Netty version to one compatible with your grpc-netty release (use the netty-bom version grpc-netty declares); run dependency:tree to find conflicts and exclude stray Netty jars","Check EpollEventLoopGroup's constructors in your resolved Netty jar (javap) to confirm the (int, ThreadFactory) form exists","Upgrade or downgrade grpc-netty so its reflection target matches the Netty version in use","If you cannot change versions, supply your own EventLoopGroup via NettyChannelBuilder/NettyServerBuilder.eventLoopGroup(...) instead of relying on epoll autodetection"],"exampleFix":"// before (pom.xml — conflicting versions)\n<dependency><groupId>io.netty</groupId><artifactId>netty-all</artifactId><version>4.2.0.Final</version></dependency>\n\n// after — pin the version grpc-netty expects\n<dependencyManagement>\n  <dependencies>\n    <dependency>\n      <groupId>io.netty</groupId>\n      <artifactId>netty-bom</artifactId>\n      <version>4.1.100.Final</version>\n      <type>pom</type>\n      <scope>import</scope>\n    </dependency>\n  </dependencies>\n</dependencyManagement>","handlingStrategy":"validation","validationCode":"static boolean epollConstructorMatches() {\n  try {\n    Class.forName(\"io.netty.channel.epoll.EpollEventLoopGroup\")\n        .getConstructor(Integer.TYPE, ThreadFactory.class);\n    return true;\n  } catch (ClassNotFoundException | NoSuchMethodException e) {\n    return false;\n  }\n}\n// assert at startup: if (!epollConstructorMatches()) log.error(\"Netty version incompatible with grpc-netty epoll transport\");","typeGuard":null,"tryCatchPattern":"try {\n  return io.grpc.netty.Utils.createEpollEventLoopGroup(parallelism, threadFactory);\n} catch (RuntimeException e) {\n  if (e.getCause() instanceof NoSuchMethodException) {\n    throw new IllegalStateException(\n        \"Netty version on classpath lacks EpollEventLoopGroup(int, ThreadFactory); align netty-bom with grpc-netty\", e);\n  }\n  throw e;\n}","preventionTips":["Import netty-bom at the exact version grpc-netty declares; never let netty-all override it","Run dependency:tree in CI and fail on multiple Netty versions","Check EpollEventLoopGroup constructors with javap after any Netty upgrade","Prefer builder.eventLoopGroup(...) with a concrete group over reflective transport selection when versions drift","Keep grpc-netty and Netty upgraded together"],"tags":["netty","grpc","reflection","version-conflict","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"}