JVM附加Agent时触发AgentLoadException:102错误如何解决

错误码102对应ATTACH_ERROR_STARTFAIL，代表attach请求已经被目标JVM接收，但Agent在目标JVM内启动阶段失败，和attach链路的权限、进程通信问题无关，直接按以下优先级排查：

异常与加载代码参考 #

异常堆栈：

com.sun.tools.attach.AgentLoadException: 102
    at jdk.attach/sun.tools.attach.HotSpotVirtualMachine.loadAgentLibrary(HotSpotVirtualMachine.java:109)
    at jdk.attach/sun.tools.attach.HotSpotVirtualMachine.loadAgentLibrary(HotSpotVirtualMachine.java:120)
    at jdk.attach/sun.tools.attach.HotSpotVirtualMachine.loadAgent(HotSpotVirtualMachine.java:148)
    at Main.main(Main.java:31)

典型Agent加载代码：

try {
    attach.loadAgent(agent.getAbsolutePath() , "1");
    System.out.println("Agent was loaded.");
} catch (AgentLoadException e) {
    System.err.println("Agent failed to load: ");
    e.printStackTrace();
} catch (AgentInitializationException e) {
    System.err.println("Agent loaded, but failed to initialize: ");
    e.printStackTrace();
} catch (IOException e) {
    e.printStackTrace();
}

排查步骤（按踩坑概率从高到低排序） #

• 检查Agent入口方法是否符合规范
  动态attach的Jar类型Agent必须实现严格签名的入口方法：public static void agentmain(String agentArgs, Instrumentation inst)，方法名拼写错误、缺少参数、非public static修饰、返回值不是void都会直接触发102。注意premain方法仅支持JVM启动时-javaagent参数加载，动态attach场景不会识别premain作为入口。
  如果是C/C++编写的本地Agent（.so/.dll文件），需要确认动态库导出了Agent_OnAttach函数，且动态库的CPU架构（32/64位）和目标JVM架构完全一致。
• 检查Agent打包配置是否正确
  Agent Jar包的META-INF/MANIFEST.MF文件必须正确声明Agent-Class: <Agent类全限定名>属性，属性值写错、类名后带多余空格、MANIFEST格式不符合规范、被其他依赖的MANIFEST文件覆盖，都会导致JVM找不到Agent入口类。
  注意不要用Spring Boot默认的可执行Jar打包方式打Agent包，Spring Boot嵌套Jar的BOOT-INF/classes结构无法被JVM的Agent类加载器识别，会直接报类找不到。
• 直接查看目标JVM的输出日志定位根因
  102错误不会把Agent启动的真实异常返回给attach客户端，所有启动阶段的报错（类缺失、方法执行异常、权限错误）都会打印在目标JVM的标准输出/错误流中：前台启动的JVM直接看控制台日志，后台运行的JVM找对应的业务日志文件，90%以上的场景能直接看到明确的报错信息，比如NoClassDefFoundError、ClassNotFoundException（大多是Agent打包时没把自身依赖打进Jar包导致）。
• 检查JDK版本与模块权限兼容性
  编译Agent的JDK大版本不能高于目标JVM版本，比如用JDK17编译的Agent无法在JDK8进程中加载，会触发类版本不兼容错误。JDK9及以上高版本JVM如果要访问JDK内部API，需要在MANIFEST.MF中添加对应的Add-Opens声明，否则会抛出模块访问权限异常导致Agent启动失败。
• 排查Agent启动逻辑的致命错误
  如果agentmain方法内主动调用了System.exit()、触发了JNI调用崩溃、执行了死循环阻塞启动线程，也会返回102错误，这类场景一般会在目标JVM的工作目录下生成hs_err_pid<进程号>.log的崩溃日志，直接查看日志中的崩溃栈即可定位。

快速验证手段 #

先写一个无任何依赖的最简Agent做基线验证，排除环境问题：

import java.lang.instrument.Instrumentation;
public class SimpleTestAgent {
    public static void agentmain(String args, Instrumentation inst) {
        System.out.println("Agent load success");
    }
}

正确配置MANIFEST.MF的Agent-Class后用原有逻辑加载，如果最简Agent能加载成功，说明问题出在原有Agent的代码、依赖或打包配置上；如果最简Agent也加载失败，再排查JDK版本、架构匹配问题。

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