{"record":{"id":"1ee6a4213800d269","repo":"pinpoint-apm/pinpoint","slug":"failed-to-load-plugin-class-classname-with-clas-1ee6a4","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/PluginClassInjector.java","lineNumber":80,"sourceCode":"\n    @Override\n    public <T> Class<? extends T> injectClass(ClassLoader classLoader, String className) {\n        try {\n            if (bootstrapCore.isBootstrapPackage(className)) {\n                return bootstrapCore.loadClass(className);\n            }\n\n            if (bootstrapClassLoader == classLoader) {\n                return bootstrapClassLoaderHandler.injectClass(null, className);\n            } else if (classLoader instanceof URLClassLoader) {\n                return urlClassLoaderHandler.injectClass(classLoader, className);\n            } else {\n                return plainClassLoaderHandler.injectClass(classLoader, className);\n            }\n        } catch (Throwable e) {\n            // fixed for LinkageError\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    }\n\n    @Override\n    public InputStream getResourceAsStream(ClassLoader targetClassLoader, String internalName) {\n        try {\n            if (bootstrapCore.isBootstrapPackageByInternalName(internalName)) {\n                return bootstrapCore.openStream(internalName);\n            }\n            if (targetClassLoader == null) {\n                return bootstrapClassLoaderHandler.getResourceAsStream(null, internalName);\n            } else if (targetClassLoader instanceof URLClassLoader) {\n                final URLClassLoader urlClassLoader = (URLClassLoader) targetClassLoader;\n                return urlClassLoaderHandler.getResourceAsStream(urlClassLoader, internalName);\n            } else {\n                return plainClassLoaderHandler.getResourceAsStream(targetClassLoader, internalName);\n            }\n        } catch (Throwable e) {","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/PluginClassInjector.java#L62-L98","documentation":"PluginClassInjector.injectClass() is the single entry point that loads plugin classes into application classloaders, dispatching to bootstrap/URLClassLoader/plain handlers. Any Throwable escaping those handlers (IOException reading the jar, 'interface not found' PinpointException, LinkageError, etc.) is caught and rethrown as a PinpointException wrapping the original cause. The message only names the class and classloader — the actionable information is in the cause chain.","triggerScenarios":"Any failure inside urlClassLoaderHandler.injectClass() (addURL reflection failure, 'invalid ClassLoader') or plainClassLoaderHandler.injectClass() (jar read IOException from readJar(), missing-interface PinpointException, ClassNotFoundException wrapped as RuntimeException, LinkageError/duplicate class definition) while injecting a plugin class into the target application classloader.","commonSituations":"Corrupted or unreadable plugin jars; incomplete plugin jars missing dependency interfaces; running the agent on a JDK where reflective defineClass/addURL is blocked (module system restrictions); plugin classes compiled for a higher class-file version than the target JVM; two plugins defining the same class into one classloader.","solutions":["Read the full logged stack trace ('Failed to load plugin class ...') and fix the root cause it names (jar read fail, interface not found, reflective access, etc.).","Verify the plugin jar is complete and readable: `unzip -t`, correct permissions, and matching plugin/agent versions.","Confirm the target JVM supports the plugin classes' class-file version (plugin built with a newer JDK than the app's JVM — rebuild plugin with --release matching the runtime).","Check the plugin dir for duplicate or overlapping plugin jars; remove older versions.","If reflective access is the cause, upgrade the pinpoint agent to a version compatible with your JDK or add the required --add-opens/--add-exports JVM flags.","Test the plugin outside pinpoint (plain loadClass) to confirm the jar is self-consistent."],"exampleFix":"// caller side: always inspect the cause, the message is only a wrapper\ntry {\n    injector.injectClass(appClassLoader, \"com.example.PluginTransformer\");\n} catch (PinpointException e) {\n    logger.error(\"plugin injection failed; root cause:\", e.getCause());\n    // fix root cause (jar integrity / JDK flags / version alignment) before retrying\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    Class<?> c = injector.injectClass(targetClassLoader, pluginClassName);\n} catch (PinpointException e) {\n    // this message is only a wrapper; the actionable info is the cause\n    Throwable root = e;\n    while (root.getCause() != null) root = root.getCause();\n    logger.error(\"plugin injection of {} failed, root cause {}: {}\",\n            pluginClassName, root.getClass().getName(), root.getMessage());\n    // dispatch on root cause: IOException -> jar integrity; 'not found' -> packaging; LinkageError -> duplicates/JDK\n}","preventionTips":["Always log the full stack trace (with causes), not just e.getMessage().","Keep plugin jars complete, checksum-verified, and version-matched to the agent.","Test the target JDK against the agent version matrix before upgrading the app JVM.","Check the plugin directory for duplicate/overlapping jars at deploy time.","Run the agent in staging with debug logging enabled for plugin loading before production rollouts."],"tags":["java","pinpoint-agent","plugin-loading","classloader","wrapped-exception"],"backgroundTag":"class-loading-failed","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"}