使用ByteBuddy Java Agent运行Web应用时出现IllegalStateException问题排查

问题 #

运行基于Dropwizard和Lombok构建的Web应用时，多个类触发ByteBuddy错误，典型报错日志如下：

[Byte Buddy] ERROR com.xxxx.xxxx.xxx.x.xxxxRequest [sun.misc.Launcher$AppClassLoader@18b4aac2, null, loaded=false]
java.lang.IllegalStateException: Unexpected type reference on method: 19
    at net.bytebuddy.pool.TypePool$Default$TypeExtractor$MethodExtractor.visitTypeAnnotation(TypePool.java:8198)
    at net.bytebuddy.jar.asm.ClassReader.readMethod(ClassReader.java:1213)
    at net.bytebuddy.jar.asm.ClassReader.accept(ClassReader.java:679)
    at net.bytebuddy.jar.asm.ClassReader.accept(ClassReader.java:391)
    at net.bytebuddy.pool.TypePool$Default.parse(TypePool.java:1176)
    at net.bytebuddy.pool.TypePool$Default.doDescribe(TypePool.java:1160)
    at net.bytebuddy.pool.TypePool$Default$WithLazyResolution.access$401(TypePool.java:1240)
    at net.bytebuddy.pool.TypePool$Default$WithLazyResolution.doResolve(TypePool.java:1338)
    at net.bytebuddy.pool.TypePool$Default$WithLazyResolution$LazyTypeDescription.delegate(TypePool.java:1407)
    at net.bytebuddy.description.type.TypeDescription$AbstractBase$OfSimpleType$WithDelegation.getDeclaredAnnotations(TypeDescription.java:8101)
    at net.bytebuddy.matcher.DeclaringAnnotationMatcher.matches(DeclaringAnnotationMatcher.java:48)
    at net.bytebuddy.matcher.DeclaringAnnotationMatcher.matches(DeclaringAnnotationMatcher.java:27)
    at net.bytebuddy.agent.builder.AgentBuilder$RawMatcher$ForElementMatchers.matches(AgentBuilder.java:1292)
    at net.bytebuddy.agent.builder.AgentBuilder$Default$Transformation$Simple.matches(AgentBuilder.java:9983)
    at net.bytebuddy.agent.builder.AgentBuilder$Default$Transformation$Simple.resolve(AgentBuilder.java:9996)
    at net.bytebuddy.agent.builder.AgentBuilder$Default$Transformation$Compound.resolve(AgentBuilder.java:10252)
    at net.bytebuddy.agent.builder.AgentBuilder$Default$ExecutingTransformer.resolve(AgentBuilder.java:10584)
    at net.bytebuddy.agent.builder.AgentBuilder$Default$ExecutingTransformer.doTransform(AgentBuilder.java:10551)
    at net.bytebuddy.agent.builder.AgentBuilder$Default$ExecutingTransformer.transform(AgentBuilder.java:10514)
    at sun.instrument.TransformerManager.transform(TransformerManager.java:188)
    at sun.instrument.InstrumentationImpl.transform(InstrumentationImpl.java:428)
    at java.lang.ClassLoader.defineClass1(Native Method)
    at java.lang.ClassLoader.defineClass(ClassLoader.java:756)
    at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142)
    at java.net.URLClassLoader.defineClass(URLClassLoader.java:468)
    at java.net.URLClassLoader.findClass(URLClassLoader.java:362)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:418)
    at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:355)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:351)
    at java.lang.Class.forName0(Native Method)
    at java.lang.Class.forName(Class.java:348)

当前使用ByteBuddy版本为1.12.6，且该Agent在仅包含单个API调用的简单应用中运行正常，请问该问题的成因是什么？

成因分析 #

• ByteBuddy内置ASM版本兼容性不足：ByteBuddy 1.12.6依赖的ASM版本无法正确解析Lombok生成的方法类型注解。Lombok在处理@Data、@Builder等注解时，会生成带有特殊类型注解的字节码，旧版ASM解析这类注解时会触发Unexpected type reference异常。
• 复杂类字节码超出旧版ByteBuddy处理能力：简单应用的类结构单一，而Dropwizard Web应用中的请求类（如日志中的xxxxRequest）通常带有大量Lombok注解，生成的字节码包含更多泛型、元数据和复杂注解结构，ByteBuddy 1.12.6的类型解析逻辑无法处理这些复杂场景。
• 类加载流程冲突：Dropwizard应用的类加载顺序更复杂，ByteBuddy Agent在拦截类加载时，尝试解析尚未完全加载的类字节码，导致类型引用解析失败。简单应用类加载流程简单，不会触发该冲突。
• Lombok与ByteBuddy版本不匹配：若使用的Lombok版本较新，其生成的字节码格式超出了ByteBuddy 1.12.6的兼容范围，这种兼容性缺口在复杂类中会暴露为解析错误。

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