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.

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

• defineAgentPackage fail: Caused by:
• moduleSupport load fail Caused by:
• - agentId
• - agentName
• AgentOption

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

Appendix: 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)