pinpoint-apm/pinpoint · critical · IllegalStateException

ModuleSupportFactory not found Caused by:

Error message

ModuleSupportFactory not found Caused by:

What it means

ModuleBootLoader.getModuleSupportFactoryClass does Class.forName("com.navercorp.pinpoint.bootstrap.java9.module.ModuleSupportFactory", false, parentClassLoader). If that class is not visible from the parent classloader, IllegalStateException 'ModuleSupportFactory not found Caused by:' is thrown. The agent cannot bootstrap its Java 9+ module support.

Source

Thrown at agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/ModuleBootLoader.java:77

    void defineAgentModule(ClassLoader classLoader, URL[] jarFileList) {
        if (moduleSupport == null) {
            throw new IllegalStateException("moduleSupport not loaded");
        }
        try {
            Method definePinpointPackage = this.moduleSupport.getClass().getDeclaredMethod("defineAgentModule", ClassLoader.class, URL[].class);
            definePinpointPackage.invoke(moduleSupport, classLoader, jarFileList);
        } catch (Exception ex) {
            throw new IllegalStateException("defineAgentPackage fail: Caused by:" + ex.getMessage(), ex);
        }
    }


    private Class<?> getModuleSupportFactoryClass(ClassLoader parentClassLoader) {
        try {
            return Class.forName("com.navercorp.pinpoint.bootstrap.java9.module.ModuleSupportFactory", false, parentClassLoader);
        } catch (ClassNotFoundException ex) {
            throw new IllegalStateException("ModuleSupportFactory not found Caused by:" + ex.getMessage(), ex);
        }
    }

    private Object newModuleSupportFactory(Class<?> bootStrapClass) {
        try {
            Constructor<?> constructor = bootStrapClass.getDeclaredConstructor();
            return constructor.newInstance();
        } catch (ReflectiveOperationException e) {
            throw new IllegalStateException("ModuleSupportFactory() initialize fail", e);
        }
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Verify pinpoint-bootstrap-java9 (or the javaX jar matching your JDK) exists in the agent distribution directory
2. Match the javaX bootstrap jar to your JDK major version and Pinpoint release
3. Check that parentClassLoader is the bootstrap/agent classloader that actually contains the jar, not the app classloader
4. Reinstall the full official agent distribution rather than copying individual jars

if (parentClassLoader.getResource("com/navercorp/pinpoint/bootstrap/java9/module/ModuleSupportFactory.class") == null) {
    throw new IllegalStateException("ModuleSupportFactory jar missing — reinstall full agent distribution");
}

When it happens

Trigger: The jar containing ModuleSupportFactory (pinpoint-bootstrap-java9 or later javaX variant) is missing from the agent directory, or parentClassLoader's visibility does not include it — e.g. wrong jar set loaded for the running JDK.

Common situations: Trimmed agent distribution where only the default bootstrap jar was copied; using a JDK 9-14 build where the java15 module jar was shipped instead (or vice versa); classloader isolation in application servers excluding bootstrap jars.

Related errors

• boot class not found. bootClass: Error:
• Invalid pinpoint-bootstrap.jar:
• J9BootLoader create fail Caused by:
• initialize fail Caused by:
• invoke fail Caused by:

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