pinpoint-apm/pinpoint · error · IllegalStateException

${moduleWrap} load fail Caused by:${e.getMessage()}

Error message

${moduleWrap} load fail Caused by:${e.getMessage()}

What it means

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:...').

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/module/DefaultApplicationContext.java:156

    private void lambdaFactorySetup(Instrumentation instrumentation, ClassFileTransformModuleAdaptor classFileTransformer, JavaModuleFactory javaModuleFactory) {
        final JvmVersion version = JvmUtils.getVersion();
//      TODO version.onOrAfter(JvmVersion.JAVA_8)
        if (version.onOrAfter(JvmVersion.JAVA_9)) {
            LambdaTransformBootloader lambdaTransformBootloader = new LambdaTransformBootloader();
            lambdaTransformBootloader.transformLambdaFactory(instrumentation, classFileTransformer, javaModuleFactory);
        }
    }

    private ClassFileTransformer wrapJava9ClassFileTransformer(ClassFileTransformModuleAdaptor classFileTransformer) {
        logger.info("initialize Java9ClassFileTransformer");
        String moduleWrap = "com.navercorp.pinpoint.bootstrap.java9.module.ClassFileTransformerModuleWrap";
        try {
            Class<ClassFileTransformer> cftClass = (Class<ClassFileTransformer>) forName(moduleWrap, DefaultApplicationContext.class.getClassLoader());
            Constructor<ClassFileTransformer> constructor = cftClass.getDeclaredConstructor(ClassFileTransformModuleAdaptor.class);
            return constructor.newInstance(classFileTransformer);
        } catch (Exception e) {
            throw new IllegalStateException(moduleWrap + " load fail Caused by:" + e.getMessage(), e);
        }
    }

    private Class<?> forName(String className, ClassLoader classLoader) {
        try {
            return Class.forName(className, false, classLoader);
        } catch (ClassNotFoundException e) {
            throw new IllegalStateException(className + " not found");
        }
    }

    private ClassFileTransformer wrap(ClassFileTransformer classFileTransformer) {
        final boolean enableBytecodeDump = profilerConfig.readBoolean(ASMBytecodeDumpService.ENABLE_BYTECODE_DUMP, ASMBytecodeDumpService.ENABLE_BYTECODE_DUMP_DEFAULT_VALUE);
        if (enableBytecodeDump) {
            logger.info("wrapBytecodeDumpTransformer");
            return BytecodeDumpTransformer.wrap(classFileTransformer, profilerConfig);
        }
        return classFileTransformer;

View on GitHub (pinned to 744c3d3075)

Solutions

  1. Ensure the full agent distribution from one Pinpoint release is deployed (bootstrap + profiler jars in sync)
  2. Check the chained 'Caused by' exception: NoSuchMethodException indicates version mismatch of the wrap class constructor
  3. Verify ClassFileTransformerModuleWrap exists in bootstrap.jar (jar tf bootstrap.jar | grep ClassFileTransformerModuleWrap)
  4. If adding --add-opens/--add-exports JVM flags, re-test, since restrictive module flags can break reflective instantiation

Example fix

// before: hand-picked jars
-Xbootclasspath/a:pinpoint-bootstrap-2.3.0.jar with profiler 2.5.0
// after
use pinpoint-agent-2.5.0 distribution unmodified
Defensive patterns

Strategy: try-catch

Validate before calling

Class<?> wrap = Class.forName("com.navercorp.pinpoint.bootstrap.java9.module.ClassFileTransformerModuleWrap", false, DefaultApplicationContext.class.getClassLoader());
wrap.getDeclaredConstructor(ClassFileTransformModuleAdaptor.class); // throws if missing

Try / catch

try { transformer = wrapJava9ClassFileTransformer(adaptor); } catch (IllegalStateException e) { logger.error("ModuleWrap load failed: {}", e.getCause(), e); transformer = unwrappedTransformer; }

Prevention

When it happens

Trigger: 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().

Common situations: 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.

Related errors

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/14573680a835ada6. Report an issue: GitHub.