pinpoint-apm/pinpoint · critical · IllegalStateException

moduleSupport not loaded

Error message

moduleSupport not loaded

What it means

ModuleBootLoader.defineAgentModule first asserts that moduleSupport was initialized by loadModuleSupport; if it is still null it throws IllegalStateException 'moduleSupport not loaded'. It is a defensive state check: agent modules cannot be defined until the module system support object exists.

Source

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

    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 {
            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);
        }
    }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Ensure loadModuleSupport (via loadModuleBootLoader) is called before defineAgentModule in the boot sequence
2. Check earlier log lines for 'moduleSupport load fail' — a failed load leaves moduleSupport null and this error follows
3. On Java 8, do not invoke the module boot path at all; guard start() by JVM version
4. If modifying the fork, initialize moduleSupport unconditionally or make the state check explicit at construction time

Example fix

// before
moduleBootLoader.defineAgentModule(classLoader, jars);
// after
moduleBootLoader.loadModuleSupport(instrumentation);
moduleBootLoader.defineAgentModule(classLoader, jars);

boolean moduleSupportReady(ModuleBootLoader l) { return l != null && l.isModuleSupportLoaded(); }

When it happens

Trigger: Calling defineAgentModule (via start) before loadModuleSupport completed successfully, or after loadModuleSupport silently skipped initialization on a JVM path where module support was never created.

Common situations: Boot-order bugs in custom forks of the agent bootstrap; partial startup where loadModuleSupport was skipped for Java 8 but defineAgentModule was still called; unit tests invoking defineAgentModule in isolation.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• moduleSupport load fail Caused by:
• defineAgentPackage fail: Caused by:
• Invalid AgentClass:
• boot create failed. Error:
• boot method invoke failed. Error:

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