pinpoint-apm/pinpoint · critical · IllegalStateException

defineAgentPackage fail: Caused by:

Error message

defineAgentPackage fail: Caused by:

What it means

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.

Source

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

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

    private Object newModuleSupportFactory(Class<?> bootStrapClass) {
        try {
            Constructor<?> constructor = bootStrapClass.getDeclaredConstructor();
            return constructor.newInstance();
        } catch (ReflectiveOperationException e) {
            throw new IllegalStateException("ModuleSupportFactory() initialize fail", e);

View on GitHub (pinned to 744c3d3075)

Solutions

  1. Inspect the 'Caused by' to distinguish NoSuchMethod (version mismatch) from an implementation exception
  2. Ensure pinpoint-bootstrap-javaX and the rest of the agent jars are from the same Pinpoint release
  3. Verify each URL in jarFileList points to a readable jar on disk
  4. Check for duplicate attach of the agent in the same JVM; restart the JVM cleanly and retry
Defensive patterns

Strategy: try-catch

Validate before calling

try {
    moduleSupport.getClass().getDeclaredMethod("defineAgentModule", ClassLoader.class, URL[].class);
} catch (NoSuchMethodException e) {
    throw new IllegalStateException("ModuleSupport version mismatch: defineAgentModule(ClassLoader, URL[]) missing", e);
}

Try / catch

try {
    definePinpointPackage.invoke(moduleSupport, classLoader, jarFileList);
} catch (InvocationTargetException e) {
    logger.error("defineAgentModule failed: {}", e.getTargetException(), e);
}

Prevention

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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