调用Vertx管理的API时抛出NoSuchMethodError异常如何排查

错误现象 #

使用Vert.x框架管理API接口，发起请求调用对应API时，程序抛出NoSuchMethodError异常，错误日志如下：

io.vertx.ext.web.RoutingContext - Unhandled exception in router
java.lang.NoSuchMethodError: 'void io.vertx.ext.web.impl.RoutingContextDecorator.(io.vertx.ext.web.Route, io.vertx.ext.web.impl.RoutingContextInternal)'

错误原因 #

该错误属于典型的Vert.x组件版本不兼容问题：

• 代码编译阶段引用的vertx-web版本中，RoutingContextDecorator存在参数为(Route, RoutingContextInternal)的构造方法，但运行时类路径下加载到的vertx-web包版本和编译时版本不一致，该版本中不存在对应签名的构造方法，触发方法找不到的错误。
• 常见触发场景：
  • 手动为不同Vert.x组件（vertx-core、vertx-web、vertx其他扩展组件）指定了互不兼容的版本号，没有做统一版本管控
  • 第三方Vert.x扩展组件、框架starter传递引入了和项目指定版本不一致的vertx-web依赖，运行时被类加载器优先加载
  • 构建工具缓存了旧版本的Vert.x依赖，打包时错误将旧版本类打入运行产物
  • 运行环境（容器、应用服务器、系统类路径）预置了不同版本的Vert.x jar包，优先级高于项目打包的依赖

修复方案 #

• 统一Vert.x全组件版本：使用Vert.x官方提供的依赖BOM管控所有Vert.x相关组件的版本，不要单独给单个Vert.x依赖指定版本。以Maven为例，在pom.xml中添加如下依赖管理配置：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.vertx</groupId>
      <artifactId>vertx-stack-depchain</artifactId>
      <version>4.4.4</version> <!-- 替换为你实际使用的Vert.x统一版本号 -->
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

后续引入vertx-core、vertx-web等所有Vert.x组件时，无需声明<version>标签，会自动继承BOM中定义的统一版本，从根源避免版本差问题。如果是Gradle项目，同理引入Vert.x BOM管控版本即可。

• 排查排除传递依赖冲突：
  • Maven环境执行mvn dependency:tree命令，在输出的依赖树中搜索io.vertx:vertx-web条目，定位所有非预期版本的引入来源，在对应依赖的配置中添加exclusion规则排除错误版本的vertx-web传递依赖
  • Gradle环境执行./gradlew dependencies命令，用相同逻辑定位冲突来源，排除不兼容的传递依赖
• 清理构建缓存重新打包：执行mvn clean install（Maven）或./gradlew clean build（Gradle）命令，清理旧的构建产物和本地缓存，确保重新拉取、打包正确版本的依赖。
• 检查运行环境：如果是外部容器部署、镜像部署场景，排查运行环境的类加载路径下是否存在手动放置的其他版本Vert.x jar包，移除冲突的预置包，确保运行时加载的是项目内打包的正确版本依赖。

内容的提问来源于stack exchange，提问作者Mayank Aggarwal