{"record":{"id":"250a76163bea8161","repo":"pinpoint-apm/pinpoint","slug":"failed-to-load-plugin-class-with-classloader-250a76","errorCode":null,"errorMessage":"Failed to load plugin class {} with classLoader {}","messagePattern":"Failed to load plugin class (.+?) with classLoader (.+?)","errorType":"console","errorClass":"PinpointException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/URLClassLoaderHandler.java","lineNumber":66,"sourceCode":"    }\n\n    private final PluginConfig pluginConfig;\n\n    public URLClassLoaderHandler(PluginConfig pluginConfig) {\n        this.pluginConfig = Objects.requireNonNull(pluginConfig, \"pluginConfig\");\n    }\n\n    @Override\n    @SuppressWarnings(\"unchecked\")\n    public <T> Class<? extends T> injectClass(ClassLoader classLoader, String className) {\n        try {\n            if (classLoader instanceof URLClassLoader) {\n                final URLClassLoader urlClassLoader = (URLClassLoader) classLoader;\n                addPluginURLIfAbsent(urlClassLoader);\n                return (Class<T>) urlClassLoader.loadClass(className);\n            }\n        } catch (ReflectiveOperationException e) {\n            logger.warn(\"Failed to load plugin class {} with classLoader {}\", className, classLoader, e);\n            throw new PinpointException(\"Failed to load plugin class \" + className + \" with classLoader \" + classLoader, e);\n        }\n        throw new PinpointException(\"invalid ClassLoader\");\n    }\n\n    @Override\n    public InputStream getResourceAsStream(ClassLoader targetClassLoader, String internalName) {\n        try {\n            if (targetClassLoader instanceof URLClassLoader) {\n                final URLClassLoader urlClassLoader = (URLClassLoader) targetClassLoader;\n                addPluginURLIfAbsent(urlClassLoader);\n                return targetClassLoader.getResourceAsStream(internalName);\n            }\n        } catch (ReflectiveOperationException e) {\n            logger.warn(\"Failed to load plugin resource as stream {} with classLoader {}\", internalName, targetClassLoader, e);\n            return null;\n        }\n        return null;","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/URLClassLoaderHandler.java#L48-L84","documentation":"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').","triggerScenarios":"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.","commonSituations":"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.","solutions":["If on JDK 9+, upgrade Pinpoint agent (newer versions do not rely on URLClassLoader)","Verify the plugin jar exists in the agent plugin directory and contains the class","Check the plugin class FQCN for typos","Confirm plugin jar and agent versions are compatible"],"exampleFix":"// before\nthrow new PinpointException(\"invalid ClassLoader\");\n// after\nif (!(classLoader instanceof URLClassLoader)) {\n    logger.warn(\"ClassLoader {} is not a URLClassLoader; skipping plugin injection\", classLoader);\n    return null;\n}","handlingStrategy":"validation","validationCode":"// validate environment before starting the agent\nClassLoader cl = Thread.currentThread().getContextClassLoader();\nboolean isUrlCl = cl instanceof java.net.URLClassLoader; // false on JDK 9+ app loaders\nFile pluginDir = new File(agentHome, \"plugin\");\nboolean pluginsPresent = pluginDir.isDirectory() && pluginDir.listFiles(f -> f.getName().endsWith(\".jar\")).length > 0;","typeGuard":"boolean isUrlClassLoader(ClassLoader cl) { return cl instanceof java.net.URLClassLoader; }","tryCatchPattern":"try {\n    pluginLoader.injectClass(className, classLoader);\n} catch (PinpointException e) {\n    if (e.getMessage().contains(\"invalid ClassLoader\")) {\n        throw new IllegalStateException(\"JDK 9+ loader not supported by URLClassLoaderHandler; upgrade agent\", e);\n    }\n    throw e;\n}","preventionTips":["Check JDK version: URLClassLoader assumptions break on JDK 9+","Verify plugin jars exist and match the agent version before startup","Validate plugin class names in config","Run the agent once in a test JVM before production attach"],"tags":["classloading","plugins","classloader"],"backgroundTag":"class-not-found","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}