pinpoint-apm/pinpoint · error · IllegalStateException

JavaModuleFactory() invoke fail Caused by

Error message

JavaModuleFactory() invoke fail Caused by:${e.getMessage()}

What it means

JavaModuleFactoryFinder.lookup() reflectively instantiates the Java-9+ DefaultJavaModuleFactory via its Instrumentation constructor. If the reflective invocation fails (constructor not found, IllegalAccessException, instantiation failure, or underlying init exception), it rethrows as IllegalStateException wrapping the cause message.

Solutions

  1. Verify bootstrap.jar and profiler jar versions match exactly (same Pinpoint release); re-deploy the full agent distribution
  2. Check that com.navercorp.pinpoint.bootstrap.java9.module.DefaultJavaModuleFactory exists in the deployed bootstrap jar (jar tf bootstrap.jar | grep DefaultJavaModuleFactory)
  3. Inspect the chained cause ('Caused by') for NoSuchMethodException vs InvocationTargetException and fix accordingly (signature change means version mismatch)
  4. If not running on JDK 9+, confirm the code path is only reached on Java 9+ and check your -Djava version/launcher

Example fix

// before: mismatched jars
java -javaagent:pinpoint-bootstrap-2.4.0.jar -jar app.jar  // with profiler 2.5.0 jar copied in
// after
java -javaagent:pinpoint-bootstrap-2.5.0.jar -jar app.jar  // all agent jars from one release
Defensive patterns

Strategy: try-catch

Validate before calling

// before starting the agent on JDK9+:
Class<?> c = Class.forName("com.navercorp.pinpoint.bootstrap.java9.module.DefaultJavaModuleFactory", false, ClassLoader.getSystemClassLoader());
c.getDeclaredConstructor(java.lang.instrument.Instrumentation.class); // throws if signature missing

Try / catch

try { moduleFactory = JavaModuleFactoryFinder.lookup(instrumentation); } catch (IllegalStateException e) { logger.error("JavaModuleFactory unavailable: {}", e.getCause(), e); /* fall back to non-module path or abort startup */ }

Prevention

When it happens

Trigger: Running the Pinpoint agent on JDK 9+ where Class.getDeclaredConstructor(Instrumentation.class) or newInstance() throws ReflectiveOperationException — e.g. the DefaultJavaModuleFactory class lacks the expected (Instrumentation) constructor, its constructor throws, or its definition is not accessible to the profiler classloader.

Common situations: Bootstrap/profiler jars are mismatched versions (old bootstrap jar without DefaultJavaModuleFactory on the classpath path), a repackaged agent changed the factory signature, or the JDK module system blocks access during agent premain.

Related errors

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

Appendix: source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/javamodule/JavaModuleFactoryFinder.java:41

import java.lang.reflect.Constructor;
import java.util.Objects;

/**
 * @author Woonduk Kang(emeroad)
 */
public final class JavaModuleFactoryFinder {
    private JavaModuleFactoryFinder() {
    }

    public static JavaModuleFactory lookup(Instrumentation instrumentation) {
        Objects.requireNonNull(instrumentation, "instrumentation");

        final Class<JavaModuleFactory> javaModuleFactory = getJavaModuleFactory();
        try {
            Constructor<JavaModuleFactory> constructor = javaModuleFactory.getDeclaredConstructor(Instrumentation.class);
            return constructor.newInstance(instrumentation);
        } catch (ReflectiveOperationException e) {
            throw new IllegalStateException("JavaModuleFactory() invoke fail Caused by:" + e.getMessage(), e);
        }
    }

    private static Class<JavaModuleFactory> getJavaModuleFactory() {
        final String factoryName = "com.navercorp.pinpoint.bootstrap.java9.module.DefaultJavaModuleFactory";
        try {
            return (Class<JavaModuleFactory>) Class.forName(factoryName, false, JavaModule.class.getClassLoader());
        } catch (ClassNotFoundException e) {
            throw new IllegalStateException(factoryName + " not found");
        }
    }
}

View on GitHub (pinned to 744c3d3075)