pinpoint-apm/pinpoint · critical · PinpointException

{} ModuleFactory initialize fail

Error message

{} ModuleFactory initialize fail

What it means

DefaultModuleFactoryResolver.resolve() instantiates a ModuleFactory class by its fully-qualified name via reflection (Class.forName + getConstructor + newInstance). This error is thrown, wrapped in PinpointException, when any reflective step fails: the class cannot be found, has no no-arg constructor, is not a ModuleFactory subtype, or its constructor throws.

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/module/DefaultModuleFactoryResolver.java:75

        }
        return DEFAULT_MODULE_FACTORY.equals(moduleFactoryClazzName);
    }

    @Override
    public ModuleFactory resolve() {
        logger.info("{} ModuleFactory lookup", moduleFactoryClazzName);
        if (isDefaultModuleFactory(moduleFactoryClazzName)) {
            return new ApplicationContextModuleFactory();
        }

        ClassLoader classLoader = getClassLoader(DefaultModuleFactoryResolver.class.getClassLoader());
        try {
            final Class<? extends ModuleFactory> moduleFactoryClass =
                    (Class<? extends ModuleFactory>) Class.forName(moduleFactoryClazzName, true, classLoader);
            Constructor<? extends ModuleFactory> constructor = moduleFactoryClass.getConstructor();
            return constructor.newInstance();
        } catch (ReflectiveOperationException ex) {
            logger.warn("{} ModuleFactory initialize fail", moduleFactoryClazzName, ex);
            throw new PinpointException(moduleFactoryClazzName + " ModuleFactory initialize fail", ex);
        }
    }

    private ClassLoader getClassLoader(ClassLoader classLoader) {
        return Objects.requireNonNull(classLoader, "can't find classLoader");
    }

}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Verify the configured class name is correct and matches the exact FQCN of a ModuleFactory implementation
2. Ensure the jar containing the factory is on the agent classpath (boot-dir/lib of the Pinpoint agent)
3. Confirm the class has a public no-arg constructor
4. Check the nested ReflectiveOperationException cause in the log — ClassNotFoundException vs NoSuchMethodException vs constructor-thrown exception points to the specific fix
5. After a Pinpoint upgrade, verify the factory class was not relocated; use the built-in DefaultModuleFactory if a custom one is no longer compatible

Example fix

// before (pinpoint.config)
profiler.module.factory=com.example.MyModuleFactory
// after (class exists and has public no-arg constructor)
package com.example;
public class MyModuleFactory implements ModuleFactory {
  public MyModuleFactory() { }
  ...
}

try { Class.forName(factoryClassName, true, ClassLoader.getSystemClassLoader()); } catch (ClassNotFoundException e) { throw new IllegalStateException("ModuleFactory not on classpath: " + factoryClassName, e); }

boolean isValidModuleFactory(String fqcn) { try { Class<?> c = Class.forName(fqcn); return ModuleFactory.class.isAssignableFrom(c) && java.lang.reflect.Modifier.isPublic(c.getModifiers()); } catch (Throwable t) { return false; } }

try {
  moduleFactoryResolver.resolve(factoryClassName);
} catch (PinpointException e) {
  logger.error("Failed to resolve ModuleFactory {}; check class name and agent classpath", factoryClassName, e.getCause());
  throw e;
}

When it happens

Trigger: Starting the Pinpoint agent with profiler.module.factory (or equivalent config) pointing to a class name that is misspelled, missing from the classpath, lacking a public no-arg constructor, or whose constructor throws during initialization.

Common situations: Typo in the module factory class name in pinpoint.config, custom ModuleFactory jar not on the agent bootclasspath, renaming/moving of factory classes after a Pinpoint version upgrade, shading issues that drop the class from the built artifact.

Related errors

• unsupported data type :<fieldName>
• Unsupported type:<typeName>
• <fieldName> access error
• injectField error field:<field> value:<value>
• classPath not found. classPath:+classPath

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