Failed to load plugin resource as stream {} with classLoader

Error message

Failed to load plugin resource as stream {} with classLoader {}

What it means

Not a thrown error but a warn-level log in URLClassLoaderHandler.getResourceAsStream: when loading a plugin resource (e.g. a .class bytecode stream) from the target URLClassLoader fails with a ReflectiveOperationException, the handler logs this message and returns null. Callers treat null as 'resource unavailable' and instrumentation falls back or aborts gracefully.

Source

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

                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 {
        final URL[] urls = classLoader.getURLs();
        if (urls != null) {
            final boolean hasPluginJar = hasPluginJar(urls);
            if (!hasPluginJar) {
                if (isDebug) {
                    logger.debug("add Jar:{}", pluginConfig.getPluginJarURLExternalForm());
                }
                ADD_URL.invoke(classLoader, pluginConfig.getPluginURL());
            }
        }
    }

View on GitHub (pinned to 744c3d3075)

Solutions

Check JVM output for reflective-access warnings; add --add-opens java.base/java.net=ALL-UNNAMED on JDK 9+ if needed
Verify the resource (e.g. class file path in slash form) exists inside the plugin jar
Confirm the plugin jar is in the agent's plugin directory
Upgrade Pinpoint agent to a version with a classloader handler that supports JDK 9+

Defensive patterns

Strategy: fallback

Validate before calling

// check resource presence in the plugin jar before requesting it
String path = internalName.replace('.', '/') + ".class";
boolean exists = new java.util.jar.JarFile(pluginJar).getJarEntry(path) != null;

Try / catch

java.io.InputStream in = handler.getResourceAsStream(internalName, targetClassLoader);
if (in == null) {
    logger.warn("Plugin resource {} unavailable; falling back to non-instrumented path", internalName);
    return originalBehavior();
}

Prevention

Treat null return as expected outcome, not an exceptional crash
Use slash-separated internal names when looking up resources
Add --add-opens java.base/java.net=ALL-UNNAMED on JDK 9+ if reflective URL injection is blocked
Ensure plugin jars are deployed to the agent plugin directory

When it happens

Trigger: getResourceAsStream(internalName, targetClassLoader) is called, the target loader is a URLClassLoader, and the reflective URL injection (addPluginURLIfAbsent) or resource lookup throws - typically because the resource does not exist in the plugin jar or reflective access is denied (JDK 9+ module restrictions).

Common situations: JDK 9+ strong encapsulation blocking reflective access to URLClassLoader.addURL; plugin jar missing the resource path; internalName mismatch (slashes vs dots); plugin not deployed.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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