Spring Boot启动Mongock CLI失败报NullPointerException排查

问题背景 #

• 此前使用内嵌模式的Mongock随主应用启动自动执行数据库迁移，运行状态正常
• 切换使用Mongock CLI执行迁移时，以原有可正常运行的项目为模板，执行mvn clean package后target目录已正常生成业务jar包
• 参照官方操作指引操作仍持续报错

复现流程 #

1. 切换到Mongock CLI安装目录：

   cd D:\Programs\mongock-cli-5.0.26
   

2. 执行全量迁移命令，指定业务jar路径：

   ./mongock migrate all -aj D:\Java Projects\mongock\target\cinema.jar
   

3. 命令执行后自动生成如下shell脚本：

   #!/bin/sh
   #Generated cli script
    java -jar mongock-cli-5.0.26.jar \
    --cli-spring-jar lib/mongock-cli-springboot-5.0.26.jar \
    --cli-core-jar lib/mongock-cli-core-5.0.26.jar \
    --mongock-core-jar lib/mongock-runner-core-5.1.0.jar \
    "$@"  \
     \
   

4. Windows环境下直接执行带行尾反斜杠的命令无法识别，手动移除所有行尾反斜杠拼接得到基础命令，追加migrate all参数后执行；同时尝试通过bash script.sh执行生成的脚本：
   • 直接执行拼接命令抛出空指针异常
   • 执行bash脚本无任何输出，光标仅换行，数据库无任何变更

报错日志 #

i.m.cli.wrapper.launcher.LauncherDefault : launching Mongock CLI
runner with default launcher java.lang.NullPointerException: Cannot
invoke
"io.mongock.runner.core.builder.RunnerBuilder.buildRunner(io.mongock.runner.core.executor.operation.Operation)"
because "this.builder" is null
at io.mongock.cli.core.commands.migrate.MigrateCommand.all(MigrateCommand.java:38)

排查解决步骤 #

这个空指针不需要额外手动定义@Bean RunnerBuilder，官方文档没提这个配置是因为正常引入官方starter就会自动注册该Bean，报错核心是CLI扫描不到业务jar内的Mongock配置，集中在4个常见踩坑点，挨个核对即可：

• 首先检查项目Mongock依赖：必须引入对应SpringBoot版本的官方starter（SpringBoot2用mongock-springboot，SpringBoot3用mongock-springboot-v3），不能只引入核心包自己写初始化逻辑。CLI是靠扫描starter自动注册的RunnerBuilder Bean加载迁移逻辑的，只引核心包的自定义配置CLI识别不到，就会报builder为null的错。同时要保证构建出来的是包含所有依赖的胖jar，不要用排除了依赖的精简包构建。
• 修复路径传参问题：你传入的业务jar路径D:\Java Projects\mongock\target\cinema.jar包含空格，Windows命令行遇到空格会自动截断路径，必须给路径加双引号包裹：

  mongock.bat migrate all -aj "D:\Java Projects\mongock\target\cinema.jar"
  

  另外你之前手动拼接命令时，丢掉了最关键的-aj 业务jar路径参数——生成脚本里的"$@"是占位符，会把你输入的-aj xxx.jar参数透传进去，你手动拼的时候只抄了基础命令，没加业务jar路径，CLI根本不知道要加载哪个业务包，自然扫不到builder。
• 对齐版本：你生成的脚本里CLI版本是5.0.26，但加载的mongock-runner-core版本是5.1.0，跨小版本的核心包和CLI不兼容会直接导致Bean加载失败。要么把CLI目录lib下的mongock-runner-core-5.1.0.jar替换成和CLI同版本的5.0.26，要么把项目里的Mongock依赖整体升级到5.1.0和核心包版本对齐。
• Windows环境不要直接跑生成的.sh脚本：这个脚本是给Linux/macOS用的，Windows原生cmd/PowerShell不支持shell语法，就算装了Git Bash/WSL跑，也容易出现路径格式不兼容的问题。CLI安装包里自带Windows专用的mongock.bat脚本，直接在cmd/PowerShell里调用这个bat文件传参即可，不需要手动执行生成的shell脚本。

以上问题修复后，CLI就能正常扫描到业务包里的自动配置，正常执行迁移逻辑。

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