{"record":{"id":"d214a008e8fbcbee","repo":"pinpoint-apm/pinpoint","slug":"modulesupport-not-loaded","errorCode":null,"errorMessage":"moduleSupport not loaded","messagePattern":"moduleSupport not loaded","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/ModuleBootLoader.java","lineNumber":62,"sourceCode":"    void loadModuleSupport() {\n        try {\n            Class<?> bootStrapClass = getModuleSupportFactoryClass(parentClassLoader);\n            Object moduleSupportFactory = newModuleSupportFactory(bootStrapClass);\n\n            Method newModuleSupportMethod = moduleSupportFactory.getClass().getMethod(\"newModuleSupport\", Instrumentation.class, Consumer.class);\n            this.moduleSupport = newModuleSupportMethod.invoke(moduleSupportFactory, instrumentation, logger);\n\n            Class<?> moduleSupportSetup = moduleSupport.getClass();\n            Method setupMethod = moduleSupportSetup.getMethod(\"setup\");\n            setupMethod.invoke(moduleSupport);\n        } catch (Exception e) {\n            throw new IllegalStateException(\"moduleSupport load fail Caused by:\" + e.getMessage(), e);\n        }\n    }\n\n    void defineAgentModule(ClassLoader classLoader, URL[] jarFileList) {\n        if (moduleSupport == null) {\n            throw new IllegalStateException(\"moduleSupport not loaded\");\n        }\n        try {\n            Method definePinpointPackage = this.moduleSupport.getClass().getDeclaredMethod(\"defineAgentModule\", ClassLoader.class, URL[].class);\n            definePinpointPackage.invoke(moduleSupport, classLoader, jarFileList);\n        } catch (Exception ex) {\n            throw new IllegalStateException(\"defineAgentPackage fail: Caused by:\" + ex.getMessage(), ex);\n        }\n    }\n\n\n    private Class<?> getModuleSupportFactoryClass(ClassLoader parentClassLoader) {\n        try {\n            return Class.forName(\"com.navercorp.pinpoint.bootstrap.java9.module.ModuleSupportFactory\", false, parentClassLoader);\n        } catch (ClassNotFoundException ex) {\n            throw new IllegalStateException(\"ModuleSupportFactory not found Caused by:\" + ex.getMessage(), ex);\n        }\n    }\n","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/ModuleBootLoader.java#L44-L80","documentation":"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.","triggerScenarios":"Calling defineAgentModule (via start) before loadModuleSupport completed successfully, or after loadModuleSupport silently skipped initialization on a JVM path where module support was never created.","commonSituations":"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.","solutions":["Ensure loadModuleSupport (via loadModuleBootLoader) is called before defineAgentModule in the boot sequence","Check earlier log lines for 'moduleSupport load fail' — a failed load leaves moduleSupport null and this error follows","On Java 8, do not invoke the module boot path at all; guard start() by JVM version","If modifying the fork, initialize moduleSupport unconditionally or make the state check explicit at construction time"],"exampleFix":"// before\nmoduleBootLoader.defineAgentModule(classLoader, jars);\n// after\nmoduleBootLoader.loadModuleSupport(instrumentation);\nmoduleBootLoader.defineAgentModule(classLoader, jars);","handlingStrategy":"validation","validationCode":null,"typeGuard":"boolean moduleSupportReady(ModuleBootLoader l) { return l != null && l.isModuleSupportLoaded(); }","tryCatchPattern":null,"preventionTips":["Initialize moduleSupport in the ModuleBootLoader constructor or verify ordering in start()","Fail fast with a clear message when loadModuleSupport was skipped","Cover both Java 8 and Java 9+ boot paths in CI"],"tags":["state-management","java-modules","agent-startup"],"backgroundTag":"invalid-state-transition","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}