pinpoint-apm/pinpoint · critical · IllegalStateException

moduleSupport load fail Caused by:

Error message

moduleSupport load fail Caused by:

What it means

ModuleBootLoader.loadModuleSupport reflectively instantiates the ModuleSupportFactory (getModuleSupportFactoryClass -> newModuleSupportFactory -> newModuleSupportMethod.invoke) and invokes its setup() method. Any Exception in that chain (method missing, InvocationTargetException from setup, access failures) is wrapped in IllegalStateException 'moduleSupport load fail Caused by:'. This is only reachable on Java 9+ where the module system bootstrap path is used.

Source

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

    ModuleBootLoader(Instrumentation instrumentation, ClassLoader parentClassLoader, Consumer<String> logger) {
        this.instrumentation = Objects.requireNonNull(instrumentation, "instrumentation");
        this.parentClassLoader = parentClassLoader;
        this.logger = Objects.requireNonNull(logger, "logger");
    }

    void loadModuleSupport() {
        try {
            Class<?> bootStrapClass = getModuleSupportFactoryClass(parentClassLoader);
            Object moduleSupportFactory = newModuleSupportFactory(bootStrapClass);

            Method newModuleSupportMethod = moduleSupportFactory.getClass().getMethod("newModuleSupport", Instrumentation.class, Consumer.class);
            this.moduleSupport = newModuleSupportMethod.invoke(moduleSupportFactory, instrumentation, logger);

            Class<?> moduleSupportSetup = moduleSupport.getClass();
            Method setupMethod = moduleSupportSetup.getMethod("setup");
            setupMethod.invoke(moduleSupport);
        } catch (Exception e) {
            throw new IllegalStateException("moduleSupport load fail Caused by:" + e.getMessage(), e);
        }
    }

    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 {

View on GitHub (pinned to 744c3d3075)

Solutions

1. Check the 'Caused by' chain — find whether it is NoSuchMethod, IllegalAccess, or an exception thrown inside setup()
2. Ensure the matching pinpoint-bootstrap-javaX module jar for your JDK version is present in the agent directory
3. Use a Pinpoint release that supports your JDK version (e.g. java15 module for JDK 15+); upgrade the agent if needed
4. Add required --add-opens/--add-exports JVM flags if setup fails on module access for newer JDKs

String expected = "com.navercorp.pinpoint.bootstrap.java9.module.ModuleSupportFactory";
Class<?> factory = Class.forName(expected, false, parentClassLoader);
factory.getDeclaredConstructor();
factory.getMethod("newModuleSupport", Instrumentation.class, java.util.logging.Logger.class);

When it happens

Trigger: loadModuleSupport invoked on a Java 9+ JVM when: the ModuleSupportFactory class is absent, its constructor or newModuleSupport/ setup methods are missing or non-invokable, or setup() itself throws (module open/export rules not satisfied).

Common situations: Running the Pinpoint agent on a newer JDK where internal module rules changed; a partial agent distribution missing the bootstrap-java9/java15 module jars; launching with an illegal-access setting that blocks reflective access to java.lang.Instrumentation-related internals.

Related errors

• defineAgentPackage fail: Caused by:
• boot method invoke failed. Error:
• moduleSupport not loaded
• ModuleSupportFactory() initialize fail
• JavaModuleFactory() invoke fail Caused by:${e.getMessage()}

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