pinpoint-apm/pinpoint · error · PinpointException

invalid ClassLoader

Error message

invalid ClassLoader

What it means

PinpointException("invalid ClassLoader") thrown by URLClassLoaderHandler.injectClass when the passed classLoader is not an instance of URLClassLoader. This handler can only inject classes through URLClassLoaders; any other loader type falls through the instanceof check and hits this terminal throw.

Source

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

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

    private void addPluginURLIfAbsent(URLClassLoader classLoader) throws ReflectiveOperationException {

View on GitHub (pinned to 744c3d3075)

Solutions

1. Verify which ClassLoaderHandler implementation should serve this classloader; ensure the agent's classloader strategy matches (e.g. a non-URL handler for non-URLClassLoaders).
2. Log/print the classloader's concrete class and check whether it extends URLClassLoader; if not, this handler must not be used.
3. On JDK 9+, the app classloader is not a URLClassLoader - confirm the Pinpoint version supports the target JDK and classloader type.
4. If you control the caller, pass the URLClassLoader that actually contains the plugin classes instead of an unrelated loader.

Example fix

// before
handler.injectClass(someCustomClassLoader, className); // not a URLClassLoader
// after
if (someCustomClassLoader instanceof URLClassLoader) {
    handler.injectClass(someCustomClassLoader, className);
}

static boolean supportsInject(ClassLoader cl) { return cl instanceof URLClassLoader; }

try { return handler.injectClass(cl, name); } catch (PinpointException e) { if ("invalid ClassLoader".equals(e.getMessage())) { /* route to a compatible handler */ } throw e; }

When it happens

Trigger: injectClass(classLoader, className) called with a classloader that is not a URLClassLoader (e.g. an application server's custom classloader, OSGi loader, or the bootstrap/app loader wrapped differently).

Common situations: Running on an app server or framework whose classloader does not extend URLClassLoader (common on modern containers and JDK 9+ where the app classloader is no longer a URLClassLoader), or a mismatch between the classloader strategy selected at agent bootstrap and the loader actually handed to the handler.

Related errors

• Failed to load plugin class ${className} with classLoader ${
• ${moduleFactoryClazzName} ModuleFactory initialize fail
• system classloader is null.
• not found class. classLoader=${cl}, classInternalName=${clas
• Failed to load plugin class {} with classLoader {}

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