pinpoint-apm/pinpoint · error · PinpointException

Failed to load plugin class {} with classLoader {}

Error message

Failed to load plugin class {} with classLoader {}

What it means

Thrown by URLClassLoaderHandler.injectClass when a plugin class cannot be loaded through the target application's URLClassLoader. The handler appends the plugin jar URL to the classloader then calls loadClass; a ReflectiveOperationException (ClassNotFoundException or failure to add the URL reflectively) is wrapped into PinpointException. It is also thrown unconditionally when the classloader is not a URLClassLoader ('invalid ClassLoader').

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/URLClassLoaderHandler.java:66

    }

    private final PluginConfig pluginConfig;

    public URLClassLoaderHandler(PluginConfig pluginConfig) {
        this.pluginConfig = Objects.requireNonNull(pluginConfig, "pluginConfig");
    }

    @Override
    @SuppressWarnings("unchecked")
    public <T> Class<? extends T> injectClass(ClassLoader classLoader, String className) {
        try {
            if (classLoader instanceof URLClassLoader) {
                final URLClassLoader urlClassLoader = (URLClassLoader) classLoader;
                addPluginURLIfAbsent(urlClassLoader);
                return (Class<T>) urlClassLoader.loadClass(className);
            }
        } catch (ReflectiveOperationException e) {
            logger.warn("Failed to load plugin class {} with classLoader {}", className, classLoader, e);
            throw new PinpointException("Failed to load plugin class " + className + " with classLoader " + classLoader, e);
        }
        throw new PinpointException("invalid ClassLoader");
    }

    @Override
    public InputStream getResourceAsStream(ClassLoader targetClassLoader, String internalName) {
        try {
            if (targetClassLoader instanceof URLClassLoader) {
                final URLClassLoader urlClassLoader = (URLClassLoader) targetClassLoader;
                addPluginURLIfAbsent(urlClassLoader);
                return targetClassLoader.getResourceAsStream(internalName);
            }
        } catch (ReflectiveOperationException e) {
            logger.warn("Failed to load plugin resource as stream {} with classLoader {}", internalName, targetClassLoader, e);
            return null;
        }
        return null;

View on GitHub (pinned to 744c3d3075)

Solutions

1. If on JDK 9+, upgrade Pinpoint agent (newer versions do not rely on URLClassLoader)
2. Verify the plugin jar exists in the agent plugin directory and contains the class
3. Check the plugin class FQCN for typos
4. Confirm plugin jar and agent versions are compatible

Example fix

// before
throw new PinpointException("invalid ClassLoader");
// after
if (!(classLoader instanceof URLClassLoader)) {
    logger.warn("ClassLoader {} is not a URLClassLoader; skipping plugin injection", classLoader);
    return null;
}

// validate environment before starting the agent
ClassLoader cl = Thread.currentThread().getContextClassLoader();
boolean isUrlCl = cl instanceof java.net.URLClassLoader; // false on JDK 9+ app loaders
File pluginDir = new File(agentHome, "plugin");
boolean pluginsPresent = pluginDir.isDirectory() && pluginDir.listFiles(f -> f.getName().endsWith(".jar")).length > 0;

boolean isUrlClassLoader(ClassLoader cl) { return cl instanceof java.net.URLClassLoader; }

try {
    pluginLoader.injectClass(className, classLoader);
} catch (PinpointException e) {
    if (e.getMessage().contains("invalid ClassLoader")) {
        throw new IllegalStateException("JDK 9+ loader not supported by URLClassLoaderHandler; upgrade agent", e);
    }
    throw e;
}

When it happens

Trigger: injectClass(className, classLoader) is called with a ClassLoader that is an instance of URLClassLoader and loadClass throws ClassNotFoundException (class not in plugin jar), or the reflective addPluginURLIfAbsent call fails; also thrown when the classloader is NOT a URLClassLoader.

Common situations: Running on JDK 9+ where application/system loaders are no longer URLClassLoader; plugin jar missing or corrupt in the plugin directory; plugin class name typo in config; plugin compiled for a different Pinpoint version.

Related errors

• Failed to load plugin class ${className} with classLoader ${
• invalid ClassLoader
• Failed to load plugin resource as stream {} with classLoader
• J9BootLoader create fail Caused by:
• initialize fail Caused by:

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