{"record":{"id":"bd0c66d8ae150a85","repo":"pinpoint-apm/pinpoint","slug":"failed-to-load-plugin-class-with-classloader-bd0c66","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/PlainClassLoaderHandler.java","lineNumber":80,"sourceCode":"        this.defineClass = Objects.requireNonNull(defineClass, \"defineClass\");\n        this.pluginConfig = Objects.requireNonNull(pluginConfig, \"pluginConfig\");\n        this.pluginJarReader = new JarReader(pluginConfig.getPluginJarFile());\n    }\n\n    @Override\n    @SuppressWarnings(\"unchecked\")\n    public <T> Class<? extends T> injectClass(ClassLoader classLoader, String className) {\n        if (classLoader == Object.class.getClassLoader()) {\n            throw new IllegalStateException(\"BootStrapClassLoader\");\n        }\n\n        try {\n            if (!isPluginPackage(className, classLoader)) {\n                return loadClass(classLoader, className);\n            }\n            return (Class<T>) injectClass0(classLoader, className);\n        } catch (Exception 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    }\n\n    @Override\n    public InputStream getResourceAsStream(ClassLoader targetClassLoader, String internalName) {\n        try {\n            final String name = JavaAssistUtils.jvmNameToJavaName(internalName);\n            if (!isPluginPackage(name, targetClassLoader)) {\n                return targetClassLoader.getResourceAsStream(internalName);\n            }\n\n            getClassLoaderAttachment(targetClassLoader, internalName);\n            final InputStream inputStream = getPluginInputStream(internalName);\n            if (inputStream != null) {\n                return inputStream;\n            }\n","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/PlainClassLoaderHandler.java#L62-L98","documentation":"PlainClassLoaderHandler.injectClass loads plugin classes through the target application classloader. Any exception while checking the plugin package filter or defining the class is logged, wrapped in a PinpointException, and rethrown. It indicates the plugin class could not be defined or resolved in the application classloader.","triggerScenarios":"injectClass called for a class in a plugin package where injectClass0 (define0/class loading) throws — missing plugin resource, linkage errors, or a failure in isPluginPackage/loadClass path.","commonSituations":"Plugin class referencing classes unavailable in the app classloader; duplicate class definition (LinkageError); plugin jar corrupted; class name mismatch with packaged resource; classloader isolation (containers) preventing visibility.","solutions":["Unwrap the PinpointException cause to see the real error (ClassNotFound/Linkage/IO).","Ensure the plugin jar is on the plugin directory and its package passes the plugin package filter.","Check for duplicate plugin jars defining the same class causing LinkageError.","Verify the class's dependencies exist in the target application classloader."],"exampleFix":"// before\nClass<?> c = injector.injectClass(classLoader, \"com.example.PluginAdvice\");\n// after\ntry {\n    Class<?> c = injector.injectClass(classLoader, \"com.example.PluginAdvice\");\n} catch (PinpointException e) {\n    logger.error(\"plugin class load failed: {}\", e.getCause(), e);\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"if (!pluginConfig.getPluginPackageFilter().accept(className, classLoader)) { throw new IllegalArgumentException(\"not a plugin package: \" + className); }","typeGuard":null,"tryCatchPattern":"try { return injector.injectClass(classLoader, className); } catch (PinpointException e) { log.error(\"plugin class {} failed: {}\", className, e.getCause(), e); throw e; }","preventionTips":["Keep one copy of each plugin jar to avoid LinkageError","Ensure plugin class dependencies exist in the target app classloader","Validate the plugin package filter config at startup","Always inspect the exception cause chain"],"tags":["classloader","plugin","class-not-found"],"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"}