pinpoint-apm/pinpoint · error · PinpointException

Failed to load plugin class ${className} with classLoader ${

Error message

Failed to load plugin class ${className} with classLoader ${classLoader}

What it means

PinpointException thrown by URLClassLoaderHandler.injectClass when a plugin-provided interceptor class cannot be loaded through the target application's URLClassLoader. The underlying reflective load (Class.forName/loadClass) failed, and the original exception is attached as the cause. Pinpoint wraps it to signal that plugin class injection into the target classloader failed.

Source

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

    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

Check the wrapped cause in the log (ClassNotFoundException name) and fix the class name referenced by the plugin metadata.
Verify the plugin jar exists in the agent's plugin directory and is actually loadable from the URLClassLoader that was passed in.
Confirm the plugin class's package matches its physical location in the jar and that the jar was built with the correct Pinpoint plugin API version.
If the target classloader is not a URLClassLoader, this handler is the wrong path - check which ClassLoaderHandler is being selected.

Example fix

// before (metadata references wrong class)
interceptorClass = "com.example.GeneratedInterceptor"  // not in jar
// after
interceptorClass = "com.example.plugin.MyInterceptor"   // exists in plugin jar

Defensive patterns

Strategy: try-catch

Validate before calling

// before calling injectClass
if (!(classLoader instanceof URLClassLoader)) throw new IllegalArgumentException("need URLClassLoader");
try { Class.forName(className, false, classLoader); } catch (ClassNotFoundException e) { /* plugin jar missing */ }

Try / catch

try { return handler.injectClass(classLoader, className); } catch (PinpointException e) { logger.error("plugin class load failed for {} in {}: {}", className, classLoader, e.getCause(), e); throw e; }

Prevention

Ship the plugin jar with the agent and verify it is on the classloader's URLs
Unit-test plugin metadata class names against the packaged jar
Pin the plugin API version to the agent version

When it happens

Trigger: Calling injectClass(classLoader, className) when classLoader is a URLClassLoader but urlClassLoader.loadClass(className) throws ClassNotFoundException (or another ReflectiveOperationException) for the plugin class name.

Common situations: Plugin jar not packaged/shipped to the agent, plugin jar missing from the target classloader's URLs (addPluginURLIfAbsent failed or ran on the wrong loader), typos in the interceptor class name in plugin metadata, or plugin compiled against classes not visible to the target loader.

Related errors

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