pinpoint-apm/pinpoint · error · IllegalStateException

initialize fail Caused by:

Error message

 initialize fail Caused by:

What it means

DynamicClassLoaderFactory.getConstructor reflectively loads the named ClassLoader class and fetches its (String, URL[], ClassLoader, List) constructor. Any ReflectiveOperationException (class not found, no such constructor) is wrapped in IllegalStateException '<name> initialize fail Caused by:...'.

Source

Thrown at agent-module/bootstraps/bootstrap-core/src/main/java/com/navercorp/pinpoint/bootstrap/classloader/DynamicClassLoaderFactory.java:41

/**
 * @author Woonduk Kang(emeroad)
 */
public class DynamicClassLoaderFactory implements ClassLoaderFactory {

    private final Constructor<? extends ClassLoader> constructor;

    public DynamicClassLoaderFactory(String classLoaderName, ClassLoader classLoader) {
        this.constructor = getConstructor(classLoaderName, classLoader);
    }


    private static Constructor<? extends ClassLoader> getConstructor(String classLoaderName, ClassLoader classLoader) {
        try {
            final Class<? extends ClassLoader> classLoaderClazz =
                    (Class<? extends ClassLoader>) Class.forName(classLoaderName, true, classLoader);
            return classLoaderClazz.getDeclaredConstructor(String.class, URL[].class, ClassLoader.class, List.class);
        } catch (ReflectiveOperationException ex) {
            throw new IllegalStateException(classLoaderName +  " initialize fail Caused by:" + ex.getMessage(), ex);
        }
    }


    @Override
    public ClassLoader createClassLoader(String name, URL[] urls, ClassLoader parent, List<String> libClass) {
        try {
            return constructor.newInstance(name, urls, parent, libClass);
        } catch (ReflectiveOperationException ex) {
            throw new IllegalStateException(constructor + " invoke fail Caused by:" + ex.getMessage(), ex);
        }
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Confirm the classloader class FQCN is correct and present on the agent classpath
2. Ensure the class declares a public constructor (String, URL[], ClassLoader, List)
3. Align agent/plugin versions so the class matches the factory's expected signature
4. Read the Caused-by to distinguish ClassNotFoundException vs NoSuchMethodException

Example fix

// before
class MyLoader extends URLClassLoader { public MyLoader(URL[] urls, ClassLoader p){...} }
// after
class MyLoader extends URLClassLoader {
  public MyLoader(String name, URL[] urls, ClassLoader parent, List<String> lib) { super(name, urls, parent); }
}

Class<?> c = Class.forName(classLoaderName, false, loader);
if (Arrays.stream(c.getDeclaredConstructors()).noneMatch(k -> {
  Class<?>[] ps = k.getParameterTypes();
  return ps.length == 4 && ps[0] == String.class && ps[1] == URL[].class && ps[2] == ClassLoader.class && ps[3] == List.class;
})) throw new IllegalArgumentException(classLoaderName + " lacks required (String,URL[],ClassLoader,List) constructor");

try { factory = new DynamicClassLoaderFactory(name, parent); } catch (IllegalStateException e) { if (e.getMessage().endsWith("initialize fail Caused by:" + e.getCause().getMessage())) { log.error("Check class FQCN and constructor signature", e); } throw e; }

When it happens

Trigger: Passing a classLoaderName that is not on the classpath, or the target class exists but lacks the expected (String,URL[],ClassLoader,List) constructor, during DynamicClassLoaderFactory construction.

Common situations: Agent classpath missing pinpoint commons/bootstrap classes, renamed or refactored classloader class across Pinpoint versions, plugin providing a custom classloader without the required constructor signature.

Related errors

• invoke fail Caused by:
• bootstrapClassLoader not found Caused by:
• boot method invoke failed. Error:
• execute fail. Error:
• Unable to set registry for ServiceTypeProvider

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