{"record":{"id":"8a7b8de9010f36a9","repo":"pinpoint-apm/pinpoint","slug":"modulesupport-load-fail-caused-by","errorCode":null,"errorMessage":"moduleSupport load fail Caused by:","messagePattern":"moduleSupport load fail Caused by:","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/ModuleBootLoader.java","lineNumber":56,"sourceCode":"    ModuleBootLoader(Instrumentation instrumentation, ClassLoader parentClassLoader, Consumer<String> logger) {\n        this.instrumentation = Objects.requireNonNull(instrumentation, \"instrumentation\");\n        this.parentClassLoader = parentClassLoader;\n        this.logger = Objects.requireNonNull(logger, \"logger\");\n    }\n\n    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 {","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/ModuleBootLoader.java#L38-L74","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check the 'Caused by' chain — find whether it is NoSuchMethod, IllegalAccess, or an exception thrown inside setup()","Ensure the matching pinpoint-bootstrap-javaX module jar for your JDK version is present in the agent directory","Use a Pinpoint release that supports your JDK version (e.g. java15 module for JDK 15+); upgrade the agent if needed","Add required --add-opens/--add-exports JVM flags if setup fails on module access for newer JDKs"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"String expected = \"com.navercorp.pinpoint.bootstrap.java9.module.ModuleSupportFactory\";\nClass<?> factory = Class.forName(expected, false, parentClassLoader);\nfactory.getDeclaredConstructor();\nfactory.getMethod(\"newModuleSupport\", Instrumentation.class, java.util.logging.Logger.class);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check JDK compatibility of the agent release before deployment","Confirm the reflective method names exist in your ModuleSupportFactory version when forking","Enable agent boot debug logging on new JDK rollouts"],"tags":["reflection","java-modules","java9","agent-startup"],"backgroundTag":"module-init-failed","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"}