{"record":{"id":"e1a00456f9a3ce5a","repo":"pinpoint-apm/pinpoint","slug":"defineagentpackage-fail-caused-by","errorCode":null,"errorMessage":"defineAgentPackage fail: Caused by:","messagePattern":"defineAgentPackage 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":68,"sourceCode":"            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\n    private Object newModuleSupportFactory(Class<?> bootStrapClass) {\n        try {\n            Constructor<?> constructor = bootStrapClass.getDeclaredConstructor();\n            return constructor.newInstance();\n        } catch (ReflectiveOperationException e) {\n            throw new IllegalStateException(\"ModuleSupportFactory() initialize fail\", e);","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/ModuleBootLoader.java#L50-L86","documentation":"ModuleBootLoader.defineAgentModule reflectively looks up and invokes defineAgentModule(ClassLoader, URL[]) on the moduleSupport object. Any Exception (NoSuchMethodException, IllegalAccessException, InvocationTargetException from the implementation) is wrapped in IllegalStateException 'defineAgentPackage fail: Caused by:'. The agent's module definitions were not registered.","triggerScenarios":"moduleSupport implementation lacking the expected defineAgentModule(ClassLoader, URL[]) declared method, or that method throwing internally (e.g. a JarFile/IO error while defining one of the jarFileList URLs, or module definition rejected by the JPMS layer).","commonSituations":"Version mismatch where bootstrap's ModuleBootLoader expects an older/newer ModuleSupport interface than the java9 module jar provides; corrupted or unreadable jar URLs in jarFileList; duplicate module definitions when the agent attaches twice.","solutions":["Inspect the 'Caused by' to distinguish NoSuchMethod (version mismatch) from an implementation exception","Ensure pinpoint-bootstrap-javaX and the rest of the agent jars are from the same Pinpoint release","Verify each URL in jarFileList points to a readable jar on disk","Check for duplicate attach of the agent in the same JVM; restart the JVM cleanly and retry"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"try {\n    moduleSupport.getClass().getDeclaredMethod(\"defineAgentModule\", ClassLoader.class, URL[].class);\n} catch (NoSuchMethodException e) {\n    throw new IllegalStateException(\"ModuleSupport version mismatch: defineAgentModule(ClassLoader, URL[]) missing\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    definePinpointPackage.invoke(moduleSupport, classLoader, jarFileList);\n} catch (InvocationTargetException e) {\n    logger.error(\"defineAgentModule failed: {}\", e.getTargetException(), e);\n}","preventionTips":["Keep bootstrap and javaX module jars version-aligned","Validate jar URLs before defining modules","Avoid double-attaching the agent"],"tags":["reflection","java-modules","jar","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"}