{"record":{"id":"06173ce12699841b","repo":"pinpoint-apm/pinpoint","slug":"failed-to-load-plugin-class-classname-with-clas-06173c","errorCode":null,"errorMessage":"Failed to load plugin class ${className} with classLoader ${classLoader}","messagePattern":"Failed to load plugin class (.+?) with classLoader (.+?)","errorType":"exception","errorClass":"PinpointException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/URLClassLoaderHandler.java","lineNumber":67,"sourceCode":"\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;\n    }","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/URLClassLoaderHandler.java#L49-L85","documentation":"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.","triggerScenarios":"Calling injectClass(classLoader, className) when classLoader is a URLClassLoader but urlClassLoader.loadClass(className) throws ClassNotFoundException (or another ReflectiveOperationException) for the plugin class name.","commonSituations":"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.","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."],"exampleFix":"// before (metadata references wrong class)\ninterceptorClass = \"com.example.GeneratedInterceptor\"  // not in jar\n// after\ninterceptorClass = \"com.example.plugin.MyInterceptor\"   // exists in plugin jar","handlingStrategy":"try-catch","validationCode":"// before calling injectClass\nif (!(classLoader instanceof URLClassLoader)) throw new IllegalArgumentException(\"need URLClassLoader\");\ntry { Class.forName(className, false, classLoader); } catch (ClassNotFoundException e) { /* plugin jar missing */ }","typeGuard":null,"tryCatchPattern":"try { return handler.injectClass(classLoader, className); } catch (PinpointException e) { logger.error(\"plugin class load failed for {} in {}: {}\", className, classLoader, e.getCause(), e); throw e; }","preventionTips":["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"],"tags":["classloading","plugin","pinpoint","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"}