{"record":{"id":"14573680a835ada6","repo":"pinpoint-apm/pinpoint","slug":"modulewrap-load-fail-caused-by-e-getmessage","errorCode":null,"errorMessage":"${moduleWrap} load fail Caused by:${e.getMessage()}","messagePattern":"(.+?) load fail Caused by:(.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/module/DefaultApplicationContext.java","lineNumber":156,"sourceCode":"\n    private void lambdaFactorySetup(Instrumentation instrumentation, ClassFileTransformModuleAdaptor classFileTransformer, JavaModuleFactory javaModuleFactory) {\n        final JvmVersion version = JvmUtils.getVersion();\n//      TODO version.onOrAfter(JvmVersion.JAVA_8)\n        if (version.onOrAfter(JvmVersion.JAVA_9)) {\n            LambdaTransformBootloader lambdaTransformBootloader = new LambdaTransformBootloader();\n            lambdaTransformBootloader.transformLambdaFactory(instrumentation, classFileTransformer, javaModuleFactory);\n        }\n    }\n\n    private ClassFileTransformer wrapJava9ClassFileTransformer(ClassFileTransformModuleAdaptor classFileTransformer) {\n        logger.info(\"initialize Java9ClassFileTransformer\");\n        String moduleWrap = \"com.navercorp.pinpoint.bootstrap.java9.module.ClassFileTransformerModuleWrap\";\n        try {\n            Class<ClassFileTransformer> cftClass = (Class<ClassFileTransformer>) forName(moduleWrap, DefaultApplicationContext.class.getClassLoader());\n            Constructor<ClassFileTransformer> constructor = cftClass.getDeclaredConstructor(ClassFileTransformModuleAdaptor.class);\n            return constructor.newInstance(classFileTransformer);\n        } catch (Exception e) {\n            throw new IllegalStateException(moduleWrap + \" load fail Caused by:\" + e.getMessage(), e);\n        }\n    }\n\n    private Class<?> forName(String className, ClassLoader classLoader) {\n        try {\n            return Class.forName(className, false, classLoader);\n        } catch (ClassNotFoundException e) {\n            throw new IllegalStateException(className + \" not found\");\n        }\n    }\n\n    private ClassFileTransformer wrap(ClassFileTransformer classFileTransformer) {\n        final boolean enableBytecodeDump = profilerConfig.readBoolean(ASMBytecodeDumpService.ENABLE_BYTECODE_DUMP, ASMBytecodeDumpService.ENABLE_BYTECODE_DUMP_DEFAULT_VALUE);\n        if (enableBytecodeDump) {\n            logger.info(\"wrapBytecodeDumpTransformer\");\n            return BytecodeDumpTransformer.wrap(classFileTransformer, profilerConfig);\n        }\n        return classFileTransformer;","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/module/DefaultApplicationContext.java#L138-L174","documentation":"DefaultApplicationContext.wrapJava9ClassFileTransformer reflectively builds a ClassFileTransformerModuleWrap around the transformer to make it work under the JDK 9 module system. Any failure during Class.forName, getDeclaredConstructor, or newInstance is rethrown as IllegalStateException('<moduleWrap> load fail Caused by:...').","triggerScenarios":"On JDK 9+, when the class com.navercorp.pinpoint.bootstrap.java9.module.ClassFileTransformerModuleWrap cannot be loaded, has no constructor accepting ClassFileTransformModuleAdaptor, or its constructor throws during newInstance().","commonSituations":"Mixed-version agent jars (bootstrap jar older than profiler), custom agent builds that excluded java9 module-support classes, or running the agent on a newer JDK where module access rules changed.","solutions":["Ensure the full agent distribution from one Pinpoint release is deployed (bootstrap + profiler jars in sync)","Check the chained 'Caused by' exception: NoSuchMethodException indicates version mismatch of the wrap class constructor","Verify ClassFileTransformerModuleWrap exists in bootstrap.jar (jar tf bootstrap.jar | grep ClassFileTransformerModuleWrap)","If adding --add-opens/--add-exports JVM flags, re-test, since restrictive module flags can break reflective instantiation"],"exampleFix":"// before: hand-picked jars\n-Xbootclasspath/a:pinpoint-bootstrap-2.3.0.jar with profiler 2.5.0\n// after\nuse pinpoint-agent-2.5.0 distribution unmodified","handlingStrategy":"try-catch","validationCode":"Class<?> wrap = Class.forName(\"com.navercorp.pinpoint.bootstrap.java9.module.ClassFileTransformerModuleWrap\", false, DefaultApplicationContext.class.getClassLoader());\nwrap.getDeclaredConstructor(ClassFileTransformModuleAdaptor.class); // throws if missing","typeGuard":null,"tryCatchPattern":"try { transformer = wrapJava9ClassFileTransformer(adaptor); } catch (IllegalStateException e) { logger.error(\"ModuleWrap load failed: {}\", e.getCause(), e); transformer = unwrappedTransformer; }","preventionTips":["Keep bootstrap and profiler jars from the same release","Confirm ClassFileTransformerModuleWrap exists in the deployed bootstrap jar","Avoid restrictive --add-opens flags that break reflective instantiation"],"tags":["reflection","java9","module-system","classloader"],"backgroundTag":"module-init-failed","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}